Man pages are the cornerstone of Unix/Linux documentation, yet they often suffer from being dense and hard to navigate. Recently, I set out to improve the man pages for two essential networking tools—tcpdump and dig—by adding practical examples. The process taught me valuable lessons about documentation, collaboration, and tooling. Here are 10 key takeaways that can help anyone write clearer, more useful man pages.
1. Start with the User’s Pain Point
When I began, my main goal was to address the frustration of infrequent users who forget command syntax. By focusing on the most basic examples—like how to capture packets with tcpdump or query DNS with dig—I aimed to make the man page a quick reference, not a novel. This approach immediately resonated with users and maintainers alike. For instance, the tcpdump man page now includes a simple # tcpdump -i eth0 example, saving users from sifting through dozens of flags. The feedback was clear: examples are the fastest path to understanding.
2. Examples Are the Secret Sauce
Man pages traditionally list flags and options, but without context, they’re hard to apply. Adding concrete examples bridges theory and practice. For dig, I included examples like dig example.com ANY to show how to query all record types. This turns a dry reference into a learning tool. The community response was overwhelmingly positive—users reported being able to use the tool correctly without external tutorials. Examples reduce the cognitive load, especially for commands with dozens of options.
3. Keep It Simple for Beginners
The worst man pages assume too much prior knowledge. I deliberately avoided advanced topics and focused on the 20% of commands that cover 80% of use cases. For tcpdump, that meant starting with tcpdump -w output.pcap and tcpdump -r output.pcap. This minimalist approach ensures that even someone who has never used the tool can get started in seconds. The key is to resist the urge to show off every feature; instead, prioritize clarity over completeness.
4. Collaborate with Maintainers (Early and Often)
I reached out to maintainers Denis Ovsienko, Guy Harris, and Ondřej Surý before writing a single line. Their insights were invaluable. For example, they pointed out that tcpdump -v with -w prints a live packet count—a trick I’d have missed. By involving them early, I avoided factual errors and learned hidden features. Documentation reviews are not just about correctness; they’re a chance to discover tool nuances that even power users might overlook.
5. Documentation Review Is a Two-Way Street
Going through a formal review process forced me to verify every claim. I initially assumed dig without arguments queries the root servers, but maintainers corrected me—it queries the system’s configured resolver. This accuracy boost benefits everyone. Moreover, the reviewers often proposed better examples or flagged ambiguous wording. The end result was a man page that not only works but teaches best practices.
6. Uncover Hidden Gems by Asking
One of the most surprising findings was how many useful features are undocumented or obscure. For tcpdump, the -v flag with -w provides a real-time packet counter—perfect for long captures. I never would have discovered this on my own. Similarly, dig’s +short option simplifies output for scripting. By asking maintainers “What’s the most common mistake beginners make?” I unearthed several such gems that made examples more practical.
7. Don’t Assume Documentation Is Bad
I used to skip man pages and rely on blog posts or Stack Overflow. But this project changed my perspective. Man pages can be as engaging as a well-written blog post—if they include examples and clear explanations. I was inspired by projects like Django’s documentation, which is both correct and readable. The key is to treat man pages as a first-class learning resource, not just a reference. This mindset shift makes writing them more rewarding.
8. Avoid Learning a New Markup Language
The tcpdump man page is written in roff, a cryptic language that I had no desire to master. Instead, I wrote a simple Markdown-to-ROFF converter that maps basic Markdown (headings, lists, code blocks) to roff macros. This allowed me to focus on content, not syntax. While tools like pandoc exist, they produced output that didn’t match the existing man page style, so a custom script was more practical. You can adapt this approach for any man page project.
9. Write a Custom Converter—It’s Easier Than You Think
My Markdown-to-ROFF script was under 100 lines of Python. It converts # headings to .SH, - lists to .IP bullets, and `code` to \fB/\fI pairs. The script also adds anchors for internal links, which I used to cross-reference sections like Item 3 and Item 6. This approach saved hours and kept the source readable. The full script is available on my GitHub; feel free to adapt it for your own needs.
10. Look Ahead: Man Pages Can Be Great
This experience left me optimistic about the future of man pages. They don’t have to be intimidating or outdated. With well-chosen examples, collaboration with maintainers, and smart tooling, man pages can become a go-to resource for both beginners and experts. I plan to continue contributing examples to other tools. The next time you encounter a man page you love, thank a maintainer—and consider adding your own examples to a tool you use every day.
In summary, enhancing man pages with examples is a small effort that yields huge rewards. By focusing on simplicity, collaborating with experts, and using the right tools, anyone can make documentation that is both accurate and approachable. Whether you’re a developer or a sysadmin, you can help improve the ecosystem—one example at a time.