Introduction
Man pages have long been the cornerstone of Unix and Linux documentation, yet many users find them dense and difficult to navigate. Recognizing this, a contributor recently undertook the task of improving two beloved networking tools—tcpdump and dig—by adding practical, beginner-friendly examples to their man pages. The result is a more approachable resource that benefits both new users and those who only occasionally use these tools.
The Value of Examples in Man Pages
Examples serve as a bridge between abstract documentation and real-world usage. For infrequent users of tcpdump or dig, remembering syntax or common flags can be a challenge. By including clear, concise examples, the man page becomes a quick reference guide rather than a cryptic manual. This approach aligns with what many users have expressed: they want documentation that is accurate, concise, and immediately useful.
Improvements to dig and tcpdump Man Pages
The dig man page now includes a dedicated examples section, while the tcpdump man page’s examples have been updated and expanded. These additions were designed to cover the most basic use cases, such as performing a simple DNS lookup with dig or capturing packets on an interface with tcpdump. The goal was to provide a gentle on-ramp for beginners without overwhelming them.
Goals for Beginners and Infrequent Users
The primary objective was to address the needs of two groups: those who have never used the tool and those who use it sporadically and may forget the syntax. For example, a typical tcpdump example might show how to capture traffic on a specific interface with -i eth0 and save it to a file using -w output.pcap. Similarly, a dig example could demonstrate querying a domain’s A record with dig example.com. These straightforward examples were carefully chosen to be immediately applicable.
Why Improve Official Documentation?
There are several compelling reasons to invest in man page improvements:
- Accuracy: Man pages can achieve near-100% correctness when maintained properly, unlike blog posts or Stack Overflow answers that may become outdated.
- Review Process: Contributing changes goes through a rigorous review by tool maintainers, such as Denis Ovsienko, Guy Harris, and Ondřej Surý. This ensures that every example is not only helpful but also technically accurate.
- Discovering Hidden Features: During the review, the contributor learned valuable tips. For instance, when using
tcpdump -w out.pcap, adding the-vflag prints a live summary of captured packets, a feature unknown to many users.
The collaborative process also reveals that maintainers are aware of lesser-known but extremely useful flags and options. By incorporating this knowledge into examples, the documentation becomes richer than any single user could create alone.
Lessons Learned from the Experience
The contributor noted that working on official documentation was surprisingly rewarding. Many developers avoid man pages because they expect poor readability, but this project proved that well-crafted documentation can rival the best blog posts. Citing the Django documentation as an exemplar, the contributor expressed optimism that man pages can be both engaging and trustworthy.
One of the biggest challenges was the technical format. The tcpdump man page is written in the roff language, which is notoriously difficult to work with. Rather than learning roff from scratch, the contributor wrote a simple Markdown-to-roff script that converted basic Markdown into roff. Although tools like pandoc exist, its output was too different from the existing style, so the custom approach was chosen. This solution allowed the contributor to focus on content rather than formatting.
Conclusion
Adding practical examples to the man pages of tcpdump and dig has made these essential tools more accessible. The experience demonstrates that investing in official documentation pays off, both for users and for the open-source community. With proper examples, even the most intimidating man page can become a friendly guide.
For those interested in the final results, you can view the updated dig man page and tcpdump man page (examples sections). The contribution process also inspired further work on other man pages, proving that a small change can have a large impact.