Introduction
Manual pages (man pages) are a cornerstone of Unix-like systems, yet they often suffer from being dense and difficult to navigate. After reflecting on the value of including examples, I recently contributed to the man pages for two widely used networking tools: tcpdump and dig. The goal was to add clear, beginner-friendly examples that help users quickly grasp the most common use cases. In this article, I will walk through the motivation, the process, and the key lessons learned from this documentation effort.
The Goal: Simple, Practical Examples
The primary objective was to provide the absolute basic examples for users who either use tcpdump or dig infrequently or have never used them before. Instead of assuming deep familiarity, the new examples focus on everyday tasks: capturing packets with tcpdump or querying DNS records with dig. The idea was to make the man page useful for beginners and infrequent users—avoiding the frustration of having to search through online tutorials or forums.
This approach resonated well with both users and maintainers. By narrowing the scope to basic examples, it became easier to explain, and it addressed a common pain point: “I just need to remember the most common flags and syntax.”
Why Improve the Man Pages?
Working on official documentation offers several advantages:
- Accuracy: Man pages can achieve nearly 100% accuracy when properly reviewed. Unlike blog posts or Stack Overflow comments, man pages are maintained by the project developers themselves.
- Review process: Submitting changes for review ensures that the information is fact-checked and vetted by experts. This is far more reliable than relying on unsourced online advice.
- Unexpected insights: Even for simple questions like “What are the most commonly used tcpdump flags?”, maintainers often suggest features that are not widely known. For example, when saving packets with
tcpdump -w out.pcap, adding the-vflag prints a live summary of captured packets—a small but highly useful detail that I discovered only through this process.
Learning from Maintainers
During the review process, I collaborated with Denis Ovsienko, Guy Harris, Ondřej Surý, and other maintainers. Their feedback was invaluable. They pointed out edge cases, clarified ambiguous flag uses, and ensured that the examples were not misleading. The experience was motivating and demonstrated that man pages can evolve into something far more accessible.
I had always assumed documentation would be dry and difficult to read, so I typically skipped man pages in favor of blog posts or asking a colleague. But this project shifted my perspective: perhaps documentation can be just as engaging as a great blog post, with the added benefit of being correct. I recently started using the Django documentation, and it reinforced this optimism—it’s well-structured and approachable. The tcpdump and dig man pages can achieve a similar standard.
Overcoming the Roff Language Hurdle
The tcpdump project’s man page is written in the roff language, a formatting system that is powerful but notoriously difficult to write manually. I did not want to invest time learning roff’s intricacies, so I took a different approach. I wrote a simple Markdown-to-roff conversion script that used the same formatting conventions already present in the man page. This allowed me to draft the examples in Markdown and then automatically convert them to roff.
While tools like pandoc exist, the output it produced for this specific man page style was quite different from the existing formatting, so a custom script felt like a better fit. The result was a smooth workflow: write in Markdown, convert, and submit. The script is basic but effective, and it demonstrates that you don’t need to be a roff expert to improve man pages.
Using Markdown as an Intermediate Format
By using Markdown, I could focus on the content structure rather than the formatting details. The script handled headings, code blocks, and lists, mapping them to the corresponding roff commands. This approach could be replicated for other projects that want to modernize their man page authoring process.
The New Examples: A Walkthrough
The updated man pages now include sections with clear, command-line examples. For dig, you will find examples like querying a specific record type (e.g., dig example.com A) or performing a reverse DNS lookup. For tcpdump, the examples cover capturing packets on an interface, writing to a file, and using common filters.
The examples are not exhaustive—they deliberately stick to the most frequent scenarios. But they serve as a quick reminder for users who need to refresh their memory without reading through pages of detailed explanations.
Conclusion: Documentation Doesn’t Have to Be Bad
This experience has shown me that man pages can be improved significantly with focused effort. By adding well-chosen examples, involving maintainers, and using practical tools like a Markdown converter, we can create documentation that is both accurate and user-friendly. I encourage others to consider contributing similar improvements to their favorite tools’ man pages—the process is rewarding and the impact is immediate.
If you’re curious about the final results, check out the updated dig man page and the tcpdump man page (with examples). These pages now serve beginners and infrequent users alike, and the feedback from the community has been positive.