Enhancing Man Pages with Practical Examples: The tcpdump and dig Story
In this article, we explore the motivation and process behind adding practical examples to the man pages of two essential network tools: dig and tcpdump. The original author shares insights, challenges, and the collaborative review that made the documentation more beginner-friendly. Below are key questions and answers that delve into this effort. Jump to: Why examples? | Goal | Approach | Roff challenge | Unexpected benefit | Overall experience | Acknowledgments
Why were examples added to the dig and tcpdump man pages?
The original author noticed that including examples in man pages makes them far more useful, especially for infrequent users who might forget the exact syntax or flags. After reflecting on previous musings about man pages, they decided to put this idea into practice by adding or improving examples for two of their favorite tools: dig and tcpdump. The goal was not to replace existing documentation but to complement it with clear, real-world usage patterns. This approach helps bridge the gap between a dry reference and a practical guide, making the man page a go-to resource instead of forcing users to search blogs or Stack Overflow. The effort was well-received by maintainers, who found the addition compelling enough to incorporate into the official documentation.
What was the goal of adding these examples?
The primary goal was to provide the absolute most basic examples of how to use the tools. Many users—especially those who only occasionally need to capture network traffic with tcpdump or perform DNS lookups with dig—struggle to recall the correct commands. By including straightforward examples, the author aimed to reduce friction for beginners and infrequent users. The examples cover common tasks such as capturing packets on an interface, saving to a file, querying a specific DNS record type, or using different output formats. This focus on simplicity proved effective; maintainers agreed that such examples fill a genuine need and make the man page more approachable without sacrificing accuracy.
How did the author approach writing the man page examples?
Instead of starting from scratch, the author collaborated with experienced maintainers to identify the most commonly used flags and features. For tcpdump, they learned useful tricks like combining -w with -v to get a live packet count summary—a detail the author had never noticed before. The writing process involved drafting examples in Markdown for readability, then converting them into the roff format required by man pages. The author wrote a custom Markdown-to-roff script to automate this conversion, ensuring the output matched the existing man page conventions. This approach allowed them to focus on content quality rather than wrestling with roff syntax.
What challenge did the author face with the roff language?
The roff language used to format man pages is notoriously difficult to work with. The author found it hard to learn and time-consuming to write manually. Rather than mastering roff, they created a simple script to convert Markdown into roff, leveraging familiar Markdown syntax for headings, lists, and code blocks. While tools like pandoc exist for such conversions, their output often differed significantly from the existing man page style, so the author chose a custom solution. This pragmatic decision saved time and reduced the risk of formatting errors, letting them concentrate on the examples themselves. The script was basic but effective, proving that you don't need to be a roff expert to improve man pages.
What unexpected benefit did the author discover while working on tcpdump examples?
While updating the tcpdump man page, the author learned that combining the -w flag (to write packets to a file) with the -v flag provides a live summary of how many packets have been captured so far. This feature is extremely useful for long captures, giving real-time feedback without waiting. The author admitted they would never have discovered this on their own—it came directly from discussions with maintainers. This experience reinforced a key insight: even seemingly simple documentation improvements can uncover hidden gems. It also shows that maintainers often have deep knowledge of nuanced features that aren't immediately obvious from reading the command's help text.
What is the author's overall impression of man pages after this work?
Traditionally, the author found man pages hard to read and would skip them in favor of blog posts or asking friends. However, this project changed their perspective. They now believe that man pages can be just as engaging as a great blog post, with the added benefit of being accurate. The rigorous review process ensures that every detail is correct—something that can't be guaranteed for community-written tutorials. The author cited the Django documentation as an example of high-quality official docs and expressed optimism that man pages don't have to be bad. This positive experience motivated them to continue improving man pages, proving that with effort and collaboration, documentation can become a pleasure to read.
Who helped review the changes?
The author thanked several key contributors who reviewed the documentation updates: Denis Ovsienko, Guy Harris, Ondřej Surý, and others. Their feedback was invaluable in ensuring the examples were accurate, complete, and consistent with the rest of the man page. The review process also highlighted that maintainers are often aware of features that even experienced users might miss. By working together, they produced examples that not only serve beginners but also might teach something new to longtime users. The collaborative effort left the author feeling motivated to continue contributing to man page improvements.