Introduction

In the world of command-line tools, man pages have long been the go-to resource for understanding how to use a utility. However, they often fall short when it comes to providing clear, practical examples that help beginners or infrequent users get started quickly. This article explores a recent effort to enhance the man pages for two essential network tools—tcpdump and dig—by adding comprehensive example sections. The goal was to make these pages more accessible without sacrificing accuracy, and the experience yielded valuable insights into the documentation process.

The Goal: Providing Basic Examples for Beginners

The primary objective was simple: include the most fundamental examples of how to use tcpdump and dig. The target audience was users who might only touch these tools once in a while, or even for the first time. By offering clear, minimal examples, the hope was to reduce the learning curve and make the man page itself a practical starting point—not just a reference.

As the author put it, the approach was to say: "Hey, I want to write an examples section for beginners and infrequent users of these tools." That straightforward pitch resonated well with both users and maintainers. It’s easy to explain, aligns with what users say they want from a man page, and convinced maintainers to support the change. The result? Updated man pages that now include a dedicated examples section for both dig and tcpdump.

Why Improve Official Documentation?

Working on official documentation might seem like a chore, but it offers unique benefits that third-party tutorials or blog posts cannot match.

Accuracy Through Review

Man pages can achieve close to 100% accuracy because they undergo a thorough review process. Every flag, option, and output is validated by maintainers who know the tool inside out. This level of vetting is rarely found in a blog post or Stack Overflow answer.

Discovering Hidden Gems

Even basic questions—like "what are the most commonly used tcpdump flags?"—can lead to discoveries. During the update, the author learned from maintainer feedback that when saving packets to a file with tcpdump -w out.pcap, adding the -v flag prints a live summary of how many packets have been captured so far. This feature is incredibly useful for monitoring progress, yet it’s easy to overlook. That kind of insight comes directly from working with the experts.

Overcoming the Roff Language Barrier

One major obstacle to updating man pages is the markup language they’re often written in: roff. roff is powerful but notoriously terse and difficult to learn. The tcpdump man page, for instance, was written entirely in roff. Rather than struggle with the syntax, the author wrote a simple Markdown-to-roff conversion script that translates basic Markdown into roff, following the conventions already used in the page. While tools like pandoc exist, their output can differ significantly from the existing style, so writing a custom script provided better control. The result was a smoother editing experience that allowed focus on content rather than markup.

Lessons Learned and Future Directions

The experience of improving these man pages was rewarding and motivating. The process demonstrated that documentation doesn’t have to be hard to read or disconnected from user needs. With the right approach—clear examples, review by maintainers, and a willingness to learn—a man page can be as useful and engaging as a well-written blog post, but with the added assurance of correctness.

Thanks to the contributions of Denis Ovsienko, Guy Harris, Ondřej Surý, and other reviewers, the dig and tcpdump man pages now offer beginners a much more welcoming entry point. This effort shows that even small changes—like adding a handful of examples—can significantly improve the user experience for command-line tools.