Adding Examples to tcpdump and dig Man Pages: A Documentation Journey

I recently worked on adding examples to the man pages for two of my favorite command-line tools: tcpdump and dig. This project was inspired by feedback from last month's discussion about man pages, where many people emphasized how valuable practical examples are when learning new tools.

The goal was simple: provide the most basic, beginner-friendly examples for people who use these tools infrequently or have never used them before. I wanted to include just enough information to get someone started without overwhelming them with every possible option.

Here's what I added:

• A new dig man page examples section showing basic DNS queries
• An updated tcpdump examples section with common packet capture scenarios

Working with the maintainers has been a positive experience. I've found that explaining my goal as "writing examples for beginners and infrequent users" resonates well. It's a clear, understandable purpose that seems to align with what many users want from documentation.

Why Focus on Man Pages?

I'm currently interested in improving official documentation for a few key reasons:

Accuracy matters. Man pages can actually have close to 100% accurate information because they go through a review process. This is valuable - I've found that even for basic questions like "what are the most commonly used tcpdump flags," maintainers often know useful features I wasn't aware of.

For example, while working on the tcpdump examples, I learned that when saving packets to a file with tcpdump -w out.pcap, it's useful to add -v to print a live summary of how many packets have been captured so far. This is really helpful information that I never would have discovered on my own.

Documentation quality varies widely. I'll admit that I usually assume documentation will be hard to read, so I often skip it entirely and look for blog posts, Stack Overflow answers, or just ask a friend instead. But recently I've been feeling more optimistic - maybe documentation doesn't have to be bad? Maybe it could be as good as a great blog post while also being actually correct?

The Django documentation has been a pleasant surprise - it's really well-written and comprehensive. I'm starting to think that high-quality official documentation might be more achievable than I previously believed.

The Technical Challenges

The tcpdump man page is written in roff, a formatting language from the 1970s that I really didn't want to learn. To work around this, I wrote a basic markdown-to-roff conversion script. I could have used pandoc, but the output seemed quite different from what the existing man page used, so I thought writing my own tool might be better.

It was actually pretty cool to use an existing Markdown library to parse the Markdown AST and then implement my own code-emitting methods to format things in a way that made sense for this context.

Learning About Man Page History

This project sent me down a rabbit hole learning about the history of roff and how it's evolved since the 1970s. I was particularly inspired by learning about the mandoc project that BSD systems (and some Linux systems, and I think macOS) use for formatting man pages.

There seems to be an interesting technical and cultural divide in how documentation works on BSD versus Linux that I still haven't fully understood. I've been feeling curious about what's going on in the BSD world and how their approach to documentation differs.

The Bigger Picture

Working on these examples has reinforced my belief that good documentation is crucial for developer tools. When someone can quickly find a simple example that shows them how to accomplish their goal, it removes a significant barrier to using powerful tools like tcpdump and dig.

I'm planning to continue this work on other tools' documentation. If you have suggestions for which tools could use better examples in their man pages, I'd love to hear them. The process has been rewarding, and I'm motivated to keep improving the documentation that developers rely on every day.