How Adding Examples to tcpdump and dig Man Pages Transformed Their Usability

Recently, a developer set out to improve the man pages of two beloved networking tools—tcpdump and dig—by adding clear, practical examples. The goal was simple: help beginners and infrequent users quickly grasp the basics without diving into dense documentation. This initiative, which involved community review and creative problem-solving around the roff language, offers valuable lessons for anyone who wants to make technical documentation more approachable. Below, we explore the motivation, process, and outcomes of this effort in a Q&A format.

Why add examples to man pages?

Examples make man pages far more useful, especially for people who use a tool only occasionally. The developer noticed that many users skip traditional man pages and turn to blog posts or Stack Overflow because examples are often missing or unclear. By adding example sections, the goal was to reduce that friction. For instance, a simple example like tcpdump -i eth0 immediately shows how to start capturing packets, whereas reading through flag descriptions might still leave a beginner guessing. Examples also help maintainers reflect on what users actually do, leading to more intuitive documentation. The community responded positively because examples lower the barrier to entry without sacrificing accuracy.

How Adding Examples to tcpdump and dig Man Pages Transformed Their Usability

What were the main goals of the update?

The primary aim was to provide the absolute most basic examples for newcomers and infrequent users. For tcpdump, that meant showing commands like capturing packets on an interface, writing to a file, and reading a saved capture. For dig, examples included querying a domain for A records, MX records, or using the short output flag. The developer wanted to answer the question, “How do I start using this tool right now?” without overwhelming the reader. Another goal was to ensure every example was tested and accurate—something that’s easier to verify in a concrete example than in abstract flag descriptions. This focus on simplicity and correctness resonated with both users and maintainers.

How were these examples reviewed?

Community review played a crucial role. Experts like Denis Ovsienko, Guy Harris, and Ondřej Surý provided feedback to ensure the examples were not only correct but also reflected best practices. For example, the tcpdump suggestion to use -v alongside -w out.pcap to see a live capture count came directly from a reviewer’s experience. This collaborative process helped uncover useful features the author didn’t know about. The reviews also caught subtle mistakes in flag usage and output formatting, making the final examples reliable. The developer found the review process motivating and rewarding, proving that even small documentation changes benefit greatly from expert eyes.

What did the developer learn while working on these man pages?

One key insight was that man pages can achieve nearly 100% accuracy when properly maintained. The developer had previously assumed documentation was often outdated or incorrect, but this project showed that with focused attention and review, it could be as trustworthy as a great blog post. Another lesson was how rewarding it is to discover hidden features: for instance, the -v flag combined with -w in tcpdump provides a progress indicator—a small but valuable tip. The developer also learned that maintainers are often aware of useful edge cases that aren’t obvious from reading flag lists alone. This experience changed the developer’s outlook on documentation, making them more optimistic about its potential.

What was the biggest technical challenge?

The tcpdump man page is written in the roff language, which many find difficult to work with. Instead of learning roff from scratch, the developer created a simple markdown-to-roff script to convert Markdown content into the required format. Although existing tools like pandoc could do this, the output didn’t match the man page’s existing conventions. The custom script used similar styling to keep the new examples consistent with the rest of the page. While the developer admits it might not have been the most elegant solution, it allowed them to focus on content rather than syntax. This pragmatic approach shows that even modest automation can overcome documentation formatting barriers.

What keeps you motivated to improve documentation?

The developer drew inspiration from projects like Django’s documentation, which is widely praised for being both clear and accurate. Seeing that official docs can be just as helpful—if not more—than third-party resources was a game-changer. There’s also a sense of satisfaction in helping users solve real problems. When even a simple example like dig example.com MX saves someone from reading a lengthy manual, it feels worthwhile. The collaborative aspect, where users and maintainers work together to hone the examples, adds a community-driven energy. Ultimately, the developer hopes that this approach will encourage more people to contribute to man pages, making them a go-to resource rather than a last resort.

Tags: