This Q&A explores the effort to improve the man pages for two essential networking tools: tcpdump and dig. Inspired by the power of clear examples, the project focused on adding beginner-friendly sections to official documentation, making it easier for infrequent users to recall key usage patterns. Below, we dive into the motivations, process, and outcomes of this documentation overhaul.
What was the main goal of adding examples to the dig and tcpdump man pages?
The primary goal was to provide the absolute most basic examples for people who use these tools infrequently—or have never used them before—and struggle to remember how they work. Rather than catering to experts, the idea was to meet beginners and occasional users where they are. For instance, a simple tcpdump command like tcpdump -i eth0 or a basic dig query such as dig example.com can be invaluable. By including these straightforward use cases in the man pages (official Unix documentation), the project aimed to bridge the gap between “I know this exists” and “I can actually use it now.” The result is a resource that feels like a friendly tutorial rather than an intimidating reference.
Why improve man pages instead of relying on online tutorials or blog posts?
Man pages have a unique advantage: they can achieve nearly 100% accuracy because they’re maintained by the tool’s developers or subject-matter experts. In contrast, blog posts and Stack Overflow answers often contain outdated or incorrect information. Improving man pages means investing in a single authoritative source that lives with the software. During the review process, maintainers catch mistakes and suggest improvements that the original author might never think of. For example, while working on the tcpdump examples, the author learned that adding the -v flag when saving packets to a file (tcpdump -w out.pcap) prints a live summary of captured packets—a useful feature they’d never have discovered on their own. This collaborative accuracy makes man pages a trustworthy foundation, complementing less formal online resources.
What specific examples were added to the dig man page?
The new examples focus on real-world scenarios. For dig, the man page now includes a section showcasing queries like dig example.com for a standard lookup, dig -x 8.8.8.8 for reverse DNS resolution, and dig example.com MX for mail exchanger records. Each example explains the purpose and expected output, stripped of unnecessary flags. The selection prioritized the commands most commonly needed for network troubleshooting or fundamental DNS operations. By showing these in a clean, reproducible format, even a user who hasn’t touched dig in months can get an answer in seconds. The examples also demonstrate how to query a specific nameserver using @server syntax, which is a frequent but easily forgotten operation.
What changes were made to the tcpdump man page examples section?
The tcpdump examples were completely rewritten and expanded. Earlier versions existed, but the update added more beginner-oriented snippets. Key additions include: capturing traffic on a specific interface (tcpdump -i eth0), limiting packet count (-c 10), saving packets to a file (-w out.pcap), and reading from a saved file (-r out.pcap). The author also incorporated a tip about combining -w with -v to get a live count of captured packets—a small but powerful improvement discovered during collaboration. Moreover, the man page now explains basic packet filtering, such as tcpdump port 80 for HTTP traffic or tcpdump host 192.168.1.1 for host-specific captures. The goal remains: give someone who hasn’t used tcpdump in months enough to start debugging immediately.
How was the problem of writing man pages in the roff language avoided?
The tcpdump man page is traditionally written in roff, a typesetting language known for its steep learning curve. Rather than mastering it, the author wrote a minimal markdown-to-roff script that converts Markdown into roff syntax, following existing formatting conventions. This approach allowed focusing on content creation using Markdown’s simplicity. While tools like Pandoc could convert Markdown to roff, their output often differed significantly from the original style, requiring manual cleanup. By crafting a custom script, the author kept output consistent with the rest of the man page. Admittedly, this might not be the most scalable solution, but it worked for the specific use case. The lesson: you don’t need to become a roff expert to contribute meaningful documentation; find a workflow that lets you focus on what matters—clear examples.
What surprising lessons were learned while creating these man page examples?
Two unexpected takeaways stand out. First, the collaborative review process revealed that even simple questions like “what are the most commonly used tcpdump flags?” can uncover hidden gems from maintainers’ expertise. The -v flag with -w is a perfect example: a feature the author had never noticed but is incredibly useful for real-time feedback during packet captures. Second, the experience changed the author’s attitude toward official documentation. Previously, they’d skip man pages for blog posts or Stack Overflow, assuming they’d be hard to read. Now, they feel optimistic that documentation can be as engaging as a great blog post while being more accurate. This shift suggests that investing in structured examples can transform man pages from feared references into welcoming guides—a win for both maintainers and users.
Who helped review and improve these man page changes?
The updates wouldn’t have been possible without the dedicated reviewers from the respective projects. For tcpdump, Denis Ovsienko and Guy Harris provided careful feedback, ensuring technical accuracy and consistency with the tool’s architecture. For dig, Ondřej Surý and other contributors from the BIND team played a similar role. Their involvement highlights the importance of community-driven documentation. The author describes the experience as positive and motivating—proof that maintainers are often eager to enhance user resources when given a clear, beginner-focused proposal. If you’re considering contributing to open-source documentation, this example shows that even a modest contribution can receive warm support, especially when you articulate a simple goal: “I want to write an examples section for beginners and infrequent users.” The collaborative review process then elevates the content beyond what any single person could achieve.