Man pages are often criticized for being dense and hard to navigate, but they don't have to be. By adding clear, beginner-friendly examples, we can make powerful tools like tcpdump and dig accessible to everyone. Here's a look at the process, challenges, and benefits of enhancing official documentation.
1. Why did you decide to add examples to the tcpdump and dig man pages?
I noticed that many users, especially those who use these tools infrequently, struggle to remember command syntax and flags. They often turn to blogs or Stack Overflow instead of the man page. Adding concrete examples makes the documentation more helpful and reduces the learning curve. The maintainers were receptive because clear examples help both beginners and experienced users quickly recall common usage patterns.
2. What was the main goal when writing these examples?
The goal was to provide the absolute most basic examples for people who haven't used tcpdump or dig in a while—or have never used them at all. For instance, showing how to run a simple DNS lookup with dig example.com or capture live traffic with tcpdump -i eth0. The idea is that these snippets are immediately actionable and don't assume prior knowledge of complex options. By keeping examples focused on everyday tasks, the man page becomes a quick reference rather than a barrier.
3. How did you ensure the examples were accurate and up-to-date?
Accuracy is crucial because outdated examples can mislead users. I worked closely with the maintainers of both projects—people like Denis Ovsienko, Guy Harris, and Ondřej Surý—who reviewed every change. They caught incorrect flags, outdated syntax, and even suggested better practices. For example, they pointed out that when saving packets to a file with tcpdump -w out.pcap, adding -v prints a live summary of captured packets—a useful feature I didn't know about. This collaborative review process gives the documentation close to 100% accuracy.
4. What did you learn from maintainers while developing these examples?
I discovered that maintainers are often aware of hidden features that even experienced users miss. For instance, the -v flag with tcpdump -w was new to me. Similarly, for dig, they recommended including the +short option to reduce output clutter. Asking basic questions like “what are the most commonly used flags” revealed insights that I wouldn't have found by reading the existing man page alone. This shows that maintainers can be an invaluable resource for documentation improvements.
5. How did you handle the challenge of writing in the roff language?
The tcpdump man page is written in the roff language, which has a steep learning curve. I avoided learning roff by creating a custom Markdown-to-roff converter script. While tools like Pandoc exist, their output didn't match the existing style, so a lightweight converter was simpler. The script used similar conventions already present in the man page, making the result look natural. This approach let me focus on content quality rather than syntax details.
6. What benefits do you see from improving official documentation?
Well-crafted man pages can rival the best blog posts in clarity, with the additional advantage of being authoritative and correct. Improving documentation motivates contributors and builds trust in the tool. It also reduces the support burden on maintainers, since users find answers faster. By making these resources beginner-friendly, we encourage proper usage from the start, which benefits the entire community.
7. Any final thoughts on this experience?
I'm optimistic that documentation doesn't have to be bad. Working on these man pages was a positive experience—reviewers were supportive, and I learned a lot. I hope this inspires others to contribute to official docs of their favorite tools. Even small enhancements, like adding a few examples, can make a big difference.