5 Key Insights from Improving Man Pages for tcpdump and dig
Man pages often get a bad rap for being dense and difficult to navigate. But what if they could be as clear and helpful as a well-written blog post? Recently, I set out to add practical examples to the man pages of two indispensable network tools: tcpdump and dig. The experience taught me valuable lessons about documentation, tool usage, and the power of collaborative review. Here are the top five takeaways from that journey.
1. The Motivation Behind Better Man Pages
Man pages can actually have close to 100% accurate information, but they're often skipped in favor of blog posts or Stack Overflow. I wanted to change that by adding (or improving) examples for tcpdump and dig. The existing dig man page got its first examples, and the tcpdump man page saw its examples refreshed. The goal was simple: make these pages approachable for beginners and infrequent users. Going through a formal review process with maintainers like Denis Ovsienko, Guy Harris, and Ondřej Surý ensured the information was not only clear but also correct. Their feedback turned a personal project into a community effort that left me motivated to do more.
2. Focusing on the Most Basic Examples
When improving documentation, it's tempting to include every advanced flag. Instead, I zeroed in on the absolute most basic use cases—the ones you'd need if you haven't touched the tool in months. For tcpdump, that means showing how to capture packets on an interface, save them to a file, or filter by host. For dig, it's about looking up A records or querying a specific name server. This stripped-down approach resonated with testers, who said it answered the exact questions they had. Maintainers agreed: by limiting scope, we made the pages usable without overwhelming readers. It's a strategy that could work for any tool's man page.
3. Surprising Discoveries: The -v Flag
Even a seasoned user can learn something new from a documentation project. While crafting the tcpdump examples, I discovered that when you save 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. I had never noticed that feature, and it's incredibly useful for monitoring long captures. This came up during a review conversation—maintainers have deep knowledge of hidden gems that rarely make it into blog posts. By engaging with them, I uncovered a tip that now helps countless others. It's a reminder that even basic documentation can be a source of discovery.
4. The Challenge of the roff Language
The tcpdump man page is written in the roff language, which has a steep learning curve. I didn't want to spend weeks mastering it. Instead, I wrote a small Markdown-to-roff script that converted my examples using conventions already present in the man page. Could I have used pandoc? Possibly, but its output looked very different, so a custom script felt safer. The process taught me that you don't need to know every syntax detail to contribute—you can leverage tools you already know (like Markdown) and bridge the gap with automation. That pragmatic approach saved time and kept the focus on content quality.
5. The Value of Documentation Review
Writing the examples was only half the battle. The real magic happened during the review process. Maintainers caught inaccuracies, suggested better phrasing, and pointed out edge cases. For instance, I originally forgot to mention that dig can query specific record types beyond A. Their corrections made the examples reliable—something you can't always trust in a blog post. This collaborative filtering is what gives man pages their authority. It also challenged my assumption that documentation is always outdated or hard to read. With proper review, it can be as good as a great blog post, with the added benefit of being formally correct.
Improving man pages for tcpdump and dig was a small project with big lessons. It showed that documentation doesn't have to be intimidating—it can be concise, discoverable, and even fun to write. Whether you're a tool maintainer or a user who wants to give back, consider adding examples to your favorite man page. Start with the basics, lean on community review, and don't let unfamiliar markup languages stop you. If I can do it, so can you.