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

In a recent initiative to improve official documentation, the author focused on adding practical examples to the man pages of two essential networking tools: dig and tcpdump. This Q&A covers the motivation, process, and outcomes of that effort, highlighting the value of accurate, beginner-friendly documentation and the author's personal experience working with man page maintainers.

Why were examples added to the dig and tcpdump man pages?

The author observed that examples in man pages are extremely helpful for users, especially those who use a tool infrequently or are complete beginners. After musing about man pages the previous month, they decided to actively add or improve examples in two of their favorite tools. The dig man page received a brand-new examples section, while the tcpdump man page had its existing examples updated and expanded. This work was driven by a desire to make official documentation more approachable and practical, reducing the need for users to search alternative sources like blog posts or Q&A sites. The author also wanted to ensure the examples covered the most basic use cases, making the tools more accessible to a wider audience.

What was the goal of the new examples sections?

The primary goal was to provide absolute, basic examples for using tcpdump or dig, targeting people who use these tools rarely or for the first time. The author focused on demonstrating core functionality in a clear, straightforward manner—for instance, showing how to capture packets with tcpdump or query DNS records with dig. By keeping examples simple and directly applicable, the aim was to lower the barrier to entry and empower infrequent users to quickly get started without memorizing complex syntax. The author found that this clear goal resonated well with man page maintainers, who appreciated the emphasis on beginner and infrequent users. The approach also helped the author stay focused on what was most valuable for the audience.

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

The tcpdump project's man page is written in the roff language, which the author found difficult and did not want to learn in depth. To avoid this, they wrote a simple Markdown-to-roff script that converted Markdown content into the required roff format, using conventions already present in the existing man page. While tools like Pandoc were considered, their output differed significantly from the man page's styling, so a custom script seemed more appropriate. The author acknowledges this approach might not be perfect but found it a practical way to contribute without mastering roff. This solution allowed them to focus on writing clear examples in a familiar syntax (Markdown) rather than wrestling with obscure formatting commands.

What unexpected benefit did the author discover while working on tcpdump examples?

During the process of updating tcpdump examples, the author learned a useful feature they had never encountered before: when saving packets to a file using tcpdump -w out.pcap, adding the -v flag prints a live summary of how many packets have been captured so far. This was a revelation because the author had always assumed such progress information was unavailable. This discovery came from conversations with maintainers, highlighting a key advantage of working on official documentation—interacting with experts who know hidden features. The author notes that they would likely never have discovered this flag on their own, underscoring the value of collaborative documentation efforts in uncovering practical yet lesser-known capabilities.

What feedback did the author receive from maintainers?

The author thanked Denis Ovsienko, Guy Harris, Ondřej Surý, and others who reviewed the documentation changes. The experience was positive and motivating; the maintainers found the examples compelling and appreciated the focus on beginners and infrequent users. The review process also ensured that the information provided was nearly 100% accurate, which is a significant benefit over blog posts or community Q&A sites. The author felt encouraged to continue improving man pages, citing the constructive collaboration and the maintainers' openness to refining documentation. This feedback loop between the author and experienced maintainers helped produce high-quality examples that were both technically correct and user-friendly.

How does the author feel about documentation quality compared to blog posts?

The author admitted a past tendency to skip official documentation, assuming it would be hard to read, and instead rely on blog posts, Stack Overflow comments, or friends. However, through this project, they became optimistic that documentation doesn't have to be bad. They suggest that man pages could be just as enjoyable to read as a great blog post while also being more accurate. The author recently used Django's documentation and found it excellent, reinforcing the idea that well-crafted official docs can rival alternative sources. This shift in perspective motivates further work on man pages, aiming to make them a go-to resource rather than a last resort.

What tools or scripts were used to create the man page examples?

To bridge the gap between easy authoring and the required roff format, the author created a custom Markdown-to-roff script in Python (or similar). This script followed the man page's existing formatting conventions, allowing the author to write content in Markdown and automatically convert it to roff. Although Pandoc was considered, its output was not compatible with the existing styling, so a purpose-built converter was preferred. The script was kept basic, focusing on the specific needs of the examples section. The author acknowledges that this may not be a long-term solution but was effective for the immediate task. The approach avoided the steep learning curve of roff while producing consistent, maintainable man page content.