Enhancing tcpdump and dig Man Pages: A Q&A on Adding Examples

Man pages are often the go‑to reference for command‑line tools, but they can be daunting for newcomers. Recently, a developer set out to improve the official man pages of two essential networking utilities—tcpdump and dig—by adding practical examples. This Q&A explores the motivation behind the update, the process involved, and the surprising benefits that emerged.

• What prompted the effort?
• What was the main goal?
• Who benefits from these updates?
• How was the roff language challenge handled?
• What interesting tip surfaced?
• What broader lesson about documentation?
• Who helped review the changes?

What prompted the effort to add examples to the tcpdump and dig man pages?

It started with a simple observation: example sections are incredibly helpful for understanding how to use a tool quickly. After writing about man pages the previous month, the author realized that adding concrete, real‑world examples to the tcpdump and dig man pages would make them far more accessible. Both tools are frequently used but often only sporadically, so users tend to forget command syntax. The author decided to take action by contributing example sections directly to the official documentation. This was seen as a way to reduce the learning curve and encourage people to rely on man pages instead of third‑party sources like blog posts or Stack Overflow.

What was the main goal for the examples section?

The goal was deliberately modest: provide the absolute most basic examples of how to use each tool. The focus was on beginners and infrequent users—people who might not remember how to run a simple DNS query with dig or capture packets with tcpdump. By covering common use cases in a clear, step‑by‑step manner, the examples would serve as a quick reminder without overwhelming the reader. The author wanted to answer questions like “what’s the most common way to use this tool?” and “what flags do I really need?”. This approach proved easy to explain to maintainers and resonated with users who had long asked for better documentation.

Who are the intended beneficiaries of these updated man pages?

Primarily, the updates target anyone who uses tcpdump or dig only occasionally. System administrators, network engineers, developers, and students often turn to these tools for troubleshooting or learning. When you don’t use a command daily, it’s easy to forget its syntax and options. The new example sections act as a quick cheat sheet right inside the man page. Additionally, the work benefits maintainers themselves: by documenting common usage patterns, they ensure that users don’t rely on outdated or inaccurate information from unofficial sources. The community gains a more reliable, authoritative reference that reduces the need to search the web for basic commands.

How did the author overcome the technical challenge of writing in the roff language?

The tcpdump man page is written in roff, a formatting language many find difficult. Instead of learning roff from scratch, the author created a simple script that converts Markdown into roff. This custom script followed the conventions already used in the existing man page, making the output consistent. While tools like Pandoc could also convert Markdown to roff, their output often differed too much from the original style. By writing a dedicated converter, the author maintained control over formatting and kept the result close to what the maintainers expected. This pragmatic approach allowed the focus to remain on content rather than wrestling with roff syntax.

Can you share an interesting tip that surfaced during the work on tcpdump examples?

Absolutely! While reviewing the tcpdump examples, the author learned a highly useful trick: when saving packets to a file with tcpdump -w out.pcap, adding the -v flag causes the tool to print a live summary of how many packets have been captured so far. This real‑time feedback is invaluable for long captures or when you want to confirm that data is being written without stopping the process. The author hadn’t known about this feature before and likely wouldn’t have discovered it without discussing the documentation with the tool’s maintainers. It’s a perfect example of how official documentation can uncover hidden gems that even experienced users miss.

What broader lesson does this project offer about documentation quality?

The project challenges the common belief that official documentation is inherently hard to read or inaccurate. The author found that man pages can actually achieve nearly 100% accuracy, and through a review process with experienced maintainers, the information becomes both correct and useful. This collaboration often reveals features and best practices that the original author wasn’t aware of. The experience left the author optimistic: documentation doesn’t have to be a last resort. With thoughtful examples, it can be as engaging as a well‑written blog post—but with the added bonus of being thoroughly vetted. The goal is to make man pages a resource users want to consult.

Who contributed to reviewing these man page changes?

Several key individuals helped refine the new example sections. For tcpdump, Denis Ovsienko and Guy Harris provided thorough reviews and suggestions. For dig, Ondřej Surý lent his expertise. The author expressed gratitude for their time and insight, noting that the review process was a positive experience that left them motivated to continue improving documentation. These contributions ensured the examples were correct, consistent with the tool’s behavior, and aligned with community standards. Their involvement highlights the collaborative nature of open‑source projects, where maintainers and contributors work together to make tools more approachable for everyone.