Enhancing Man Pages with Practical Examples: A Deep Dive into dig and tcpdump

In this Q&A article, we explore the recent efforts to improve the man pages for two powerful network tools: dig and tcpdump. The focus was on adding clear, beginner-friendly examples to help infrequent users quickly grasp the essentials. We'll discuss the motivation behind this initiative, the process of ensuring accuracy, and the creative solution for writing in the challenging roff language.

1. What was the primary goal behind adding examples to the dig and tcpdump man pages?

The main objective was to provide the most basic, practical examples for users who don't use dig or tcpdump often—or have never used them before. By offering straightforward examples, the maintainers aimed to lower the barrier to entry and help these users quickly remember or learn how the tools work. The idea was to create an examples section tailored for beginners and infrequent users, making the man pages more accessible without overwhelming them with advanced options. This approach not only meets a common user need but also makes it easier to explain the value of the changes to maintainers.

2. Why is improving man page documentation considered valuable, especially for accuracy?

Man pages have the unique advantage of being able to provide near 100% accurate information—when maintained well. Unlike blog posts or Stack Overflow answers, official documentation goes through a rigorous review process that ensures every command, flag, and example is correct. This process also uncovers hidden gems: for instance, while working on the tcpdump examples, the author learned that using -v with -w out.pcap prints a live count of captured packets, a feature that might otherwise go unnoticed. Accurate man pages can be as engaging as a great blog post, but with the added benefit of being officially verified.

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

The tcpdump man page is written in the roff language, known for its steep learning curve and cryptic syntax. Rather than mastering it, the author created a simple Markdown-to-roff converter script. This script used conventions similar to those already in the man page, allowing the author to write examples in Markdown and automatically generate correct roff output. While tools like Pandoc exist, their output often differed from the existing style, so a custom script was deemed more appropriate for maintaining consistency. This pragmatic approach removed the roff hurdle and focused effort on content quality.

4. What specific new flag combination was discovered while updating the tcpdump examples?

During the update, the author learned a valuable tip: 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 is extremely useful for monitoring capture progress without having to stop the process. Previously, the author was unaware of this combination, and it's a perfect example of how the review process can uncover helpful features that even experienced users might miss.

5. Who contributed to reviewing and improving the new examples?

The author acknowledged the valuable contributions of several individuals: Denis Ovsienko, Guy Harris, Ondřej Surý, and others who reviewed the documentation changes. Their feedback ensured the examples were accurate, clear, and aligned with the tools' actual behavior. The collaborative review process not only improved the final output but also motivated the author to continue enhancing man pages in the future.

6. What personal insight did the author gain about documentation quality?

The author reflected on their own habit of skipping official documentation in favor of blog posts or asking friends, assuming it would be hard to read. However, this experience changed their perspective: documentation doesn't have to be bad. With careful crafting and review, man pages can be as good as a high-quality blog post—but with the added advantage of being correct. The author cited the Django documentation as a positive example, and expressed optimism that other projects could achieve similar readability and reliability.