When it comes to command-line tools, man pages are the go‑to reference, but they can be dense and intimidating. This Q&A explores how adding clear, beginner‑focused examples to the man pages of tcpdump and dig can make them far more useful—especially for infrequent users. The original project aimed to provide the most basic examples, and the process revealed surprising benefits, from increased accuracy to learning new tricks from maintainers. Read on to discover why this approach works and how it was implemented.
What motivated the addition of examples to the dig and tcpdump man pages?
The main motivation came from a reflection on how useful examples are in man pages. Last month’s experience showed that having concrete, real‑world examples drastically improves comprehension, especially for tools used irregularly. For dig and tcpdump, many users only need a quick refresher on basic commands—like how to capture a specific number of packets or query a DNS record. By adding a dedicated “Examples” section, the man pages become a friendlier, more approachable resource without sacrificing accuracy. The goal was to give absolute beginners and occasional users exactly what they need to start working.
How were the new examples received by the community and maintainers?
The response has been overwhelmingly positive. The maintainers found the concept compelling because it directly addresses a common pain point: documentation that assumes too much prior knowledge. Denis Ovsienko, Guy Harris, Ondřej Surý, and other reviewers provided constructive feedback that improved the examples. Their engagement also revealed that maintainers often know hidden gem features—for instance, using the -v flag with tcpdump -w out.pcap to see a live count of captured packets. This collaborative aspect made the review process valuable not just for documentation quality but also for the author’s own learning.
What specific benefits came from working on the man pages?
One major benefit is achieving near‑100% accuracy in official documentation. Unlike many blog posts or Stack Overflow answers, man pages undergo rigorous review. This means the examples are not only helpful but also correct. Additionally, the process forced the author to explore features he wouldn’t have encountered otherwise—like the -v trick mentioned earlier. This underscores that even basic questions (“What are the most commonly used tcpdump flags?”) can lead to discovering useful options that experts take for granted. Overall, the experience shifted the author’s perspective: documentation doesn’t have to be a last resort; it can be as reliable and readable as a great blog post.
How was the challenge of writing in the roff language handled?
Writing man pages typically requires the roff language, which is notoriously difficult and unintuitive. Rather than learning it from scratch, the author created a simple Markdown‑to‑roff script that converts Markdown into the appropriate format. This approach allowed focusing on content instead of syntax. Although tools like pandoc exist, their output didn’t match the existing man page conventions, so a custom script was a pragmatic choice. The result is that examples can be written in Markdown and then automatically transformed into proper roff, making maintenance and future additions much easier.
What examples were added to the dig and tcpdump man pages?
For dig, the examples cover basic DNS queries: looking up A records, MX records, and performing reverse lookups. They also show how to query a specific nameserver and format output for readability. For tcpdump, the examples include capturing traffic on a specific interface, limiting the number of packets, writing to a file, and using common filters like host and port. Both sets are designed for clarity, with minimal flags and comments explaining each command. The goal is to get the user from zero to a useful result in one step, without overwhelming them.
Why is improving man pages more valuable than relying on third‑party resources?
Relying on blog posts or Q&A sites often means trusting information that may be outdated, incomplete, or even wrong. Official man pages, when well‑maintained, are authoritative and up‑to‑date. The review process ensures accuracy, which is especially important for security‑sensitive tools like tcpdump and dig. Moreover, examples in man pages are always available offline, making them reliable even without internet access. The author’s experience with Django documentation showed that high‑quality official docs can be just as engaging as a well‑written tutorial. By following a similar philosophy, the tcpdump and dig man pages now provide a consistent, trustworthy learning resource for all users.