Enhancing Man Pages: A Practical Guide to tcpdump and dig Examples

In an effort to improve the usability of official documentation, one developer recently focused on adding practical examples to the man pages of two widely-used network tools: tcpdump and dig. The aim was to make these pages more helpful for both newcomers and those who only occasionally use the tools. Below are key insights from that experience, presented in a question-and-answer format.

What motivated the author to improve the tcpdump and dig man pages?

The author observed that examples in man pages are extremely valuable, especially for people who use a tool infrequently or are just starting out. After reflecting on feedback about man page usability, they decided to add or enhance examples for two of their favorite tools: dig and tcpdump. The goal was to provide clear, basic usage scenarios that a typical user would encounter. By focusing on the most common commands and flags, the author hoped to lower the barrier to entry and reduce the need to search for third-party tutorials. The maintainers of both projects were receptive to this idea, seeing it as a way to make the official documentation more approachable without sacrificing accuracy.

What was the main goal of the new examples sections?

The primary goal was to offer the absolute most basic examples of how to use each tool. For instance, showing how to capture packets with tcpdump or perform a DNS lookup with dig, without overwhelming the reader with every possible option. The intended audience was people who don’t use tcpdump or dig regularly and may forget the syntax between uses. By keeping examples simple and focused, the author aimed to create a quick reference that gets the user started immediately. The philosophy was: give them something they can copy and paste, and then they can explore more advanced features later. This approach aligns with feedback from users who wanted man pages to be more practical rather than exhaustive lists of flags.

How did the author ensure the accuracy of the man page updates?

Man pages have a reputation for being outdated or incorrect, but the author discovered that they can actually be very precise—if maintained properly. To ensure accuracy, the author worked closely with the projects’ maintainers during the review process. For example, Denis Ovsienko and Guy Harris reviewed the tcpdump changes, while Ondřej Surý reviewed the dig updates. This process helped catch errors and also revealed hidden features. By treating the documentation with the same rigor as code changes, the author believes man pages can achieve near-100% accuracy. The review cycle also forced the author to thoroughly test each example, ensuring that the commands actually worked as described.

What surprising discovery did the author make about tcpdump flags?

While working on the tcpdump examples, the author learned something they hadn’t known before: when saving captured packets to a file using -w out.pcap, it’s useful to also include the -v flag. Normally -v increases verbosity, but in combination with -w it causes tcpdump to print a live summary of how many packets have been captured so far. This provides real-time feedback without writing to the terminal all the packet details. The author admitted they would never have discovered this on their own—it only came to light because maintainers shared their own tips during the review. This illustrated the value of collaborative documentation writing.

How did the author handle the challenge of writing in roff language?

The tcpdump man page is written in the roff language, which the author found difficult and unappealing to learn. Instead of writing the examples directly in roff, they created a custom script that converts basic Markdown into roff format. This script used conventions similar to those already present in the man page, making the output consistent. The author considered using a tool like Pandoc but found that its output diverged too much from the existing style. Although they acknowledged the script might be a bit crude, it allowed them to focus on content rather than syntax. The approach proved effective and may serve as a template for others wanting to contribute to roff-based documents without mastering the arcane syntax.

Why does the author believe man pages can be as good as blog posts?

Historically, the author tended to skip official documentation and instead rely on blog posts, Stack Overflow, or friends for explanations. However, after this project, they feel optimistic that man pages don’t have to be impenetrable. By making examples central, using clear language, and keeping content concise, man pages can offer the same clarity and conversational tone as a well-written blog post—with the added benefit of being fact-checked by the tool’s maintainers. The author cited the Django documentation as an example of a project that achieves this balance. They now believe that with effort, any man page can become a go-to resource rather than a last resort.

What is the author's overall feeling about documentation after this experience?

The author came away feeling motivated and optimistic. They had always assumed that writing good documentation would be painful, but the process of adding examples to the tcpdump and dig man pages turned out to be rewarding. The collaboration with maintainers was positive, and the author learned new tricks about the tools themselves. They are now considering further contributions to other man pages, applying the same “examples-first” approach. The key takeaway is that documentation doesn’t have to be bad; with a focus on the beginner’s perspective and a willingness to treat it like code (including reviews), it can become a valuable part of the user experience. The author hopes this work inspires others to improve the tools they love.