Enhancing Man Pages with Practical Examples: A Look at tcpdump and dig

Introduction

Man pages are a staple of Unix-like systems, yet they often suffer from a reputation for being dense and unapproachable. A recent initiative to add practical examples to the man pages of two widely used networking tools—tcpdump and dig—aims to change that. By focusing on beginner-friendly examples, this effort makes powerful command-line utilities more accessible to occasional users and newcomers alike.

Enhancing Man Pages with Practical Examples: A Look at tcpdump and dig

The Need for Examples

Traditional man pages excel at documenting every option and flag, but they rarely show how to use a tool in everyday scenarios. This gap can leave users—especially those who only need the tool once in a while—struggling to recall basic syntax. Adding a dedicated examples section addresses this pain point directly.

The goal was straightforward: include the absolute most basic examples for each tool. For tcpdump, that means showing how to capture packets on an interface, write them to a file, or filter by host. For dig, examples cover common DNS queries like looking up A records, MX records, or performing reverse lookups. These examples are designed for people who have never used the tools before or who use them infrequently and need a quick refresher.

Real-World Impact

One of the most valuable outcomes of this work was discovering nuances that even experienced users might miss. During the review process, maintainers shared insights that improved the examples. For instance, when saving captured packets to a file with tcpdump -w out.pcap, adding the -v flag prints a live summary of packet count—a feature that many users overlook. This kind of practical tip embeds real expertise into the documentation.

The reaction from the community has been positive. Users appreciate having a clear, concise starting point. The man pages for tcpdump (with updated examples) and dig (now with a new examples section) are currently available. Thanks go to Denis Ovsienko, Guy Harris, Ondřej Surý, and other reviewers who provided valuable feedback.

Lessons from the Review Process

Working on official documentation brings several benefits. First, man pages can achieve nearly 100% accuracy because they undergo thorough review. Second, the process forces contributors to verify every claim, eliminating the guesswork found in many blog posts. Third, maintainers often know about seldom-documented features—like the -v flag trick—that dramatically improve the user experience.

Despite these advantages, the author admits to a personal bias: many developers assume that documentation is hard to read and skip it in favor of blog posts or forum answers. This project has sparked optimism that well-written man pages can be just as engaging as a good article, with the added benefit of being officially correct. The Django documentation is cited as a positive example of this ideal.

Technical Challenges

The tcpdump man page is written in the roff language, a formatting system known for its steep learning curve. Rather than mastering roff, the author wrote a simple script to convert Markdown to roff, using conventions already present in the existing man page. While tools like Pandoc were considered, its output differed significantly from the existing style, making a custom solution more practical. The script, available on GitHub, allowed rapid iteration without needing deep knowledge of roff.

This approach demonstrates that improving documentation doesn't require mastering ancient markup languages—creative workarounds can lower the barrier to contribution.

Conclusion

Adding high-quality examples to man pages is a small but impactful way to make open-source tools more user-friendly. The work on tcpdump and dig shows that with clear goals, community collaboration, and a willingness to tackle technical hurdles, even the most traditional documentation can be modernized. For anyone who has ever struggled to remember how to capture a packet or query a DNS record, these updates are a welcome resource.

To explore the examples yourself, check the man pages after updating to the latest versions of these tools. The hope is that this effort inspires similar improvements across other projects, proving that man pages can be both accurate and accessible.

Tags: