5 Valuable Lessons from Improving the tcpdump and dig Man Pages
When I set out to add practical examples to the man pages for tcpdump and dig, I didn’t expect to uncover such a wealth of insights. The goal was simple: make these powerful tools more accessible for beginners and occasional users. But along the way, I learned about hidden flags, documentation pitfalls, and the surprising power of maintainer feedback. Here are five key takeaways from that experience—each one a lesson that can help you get more out of these essential network utilities.
1. The Power of Basic Examples for Infrequent Users
Man pages are notorious for being dense and intimidating. My primary aim was to include the absolute most basic examples—commands like tcpdump -i eth0 or dig example.com—that someone who hasn’t touched the tool in months can quickly reference. This isn’t about teaching advanced techniques; it’s about bridging the gap between “I know this tool exists” and “I remember how to use it right now.” For instance, a simple example showing how to capture packets on a specific interface with -i can save a user from searching through dozens of flags. The feedback from both maintainers and users has been overwhelmingly positive: people crave straightforward, copy-paste-able examples. Including them transforms a man page from a reference document into a practical guide.
2. The Hidden Gem: Using -v with -w for Real-Time Feedback
One of the most valuable tips I picked up while working on the tcpdump man page came from a maintainer. When you save packets to a file with tcpdump -w out.pcap, it’s easy to lose track of progress—especially during long captures. But adding the -v flag prints a live summary of how many packets have been captured so far. For example: tcpdump -i eth0 -w capture.pcap -v. This simple addition gives you immediate feedback without interrupting the capture. I had never encountered this trick in any blog post or Stack Overflow answer. It’s a perfect illustration of why official documentation—when properly reviewed—can be a goldmine of correct, practical knowledge.
3. Learning from Maintainers: Uncovering Useful Features
During the review process, I collaborated with experts like Denis Ovsienko and Guy Harris. Their deep knowledge of tcpdump and dig revealed features I hadn’t considered. For example, they pointed out that dig +short is one of the most commonly used flags for quick queries—something I initially omitted. Similarly, the -c flag in tcpdump to limit the number of packets captured is a lifesaver for testing. The lesson here is that maintainers see how their tools are actually used. Engaging them during documentation work not only ensures accuracy but also teaches you best practices that aren’t always obvious from reading the source code or online forums.
4. Conquering the ROFF Language with a Custom Markdown Script
The tcpdump man page is written in the ROFF language, which is notoriously difficult to work with. Rather than learning ROFF, I wrote a simple Markdown-to-ROFF converter script. This allowed me to draft the examples in a familiar format and then automatically convert them. While tools like Pandoc exist, their output often differs from the existing man page conventions. My custom script preserved the exact styles used in the tcpdump man page (e.g., bold for commands, italics for placeholders). This approach saved hours of manual editing and reduced syntax errors. It also means that future updates can be made in Markdown and quickly regenerated. The lesson is that you don’t have to master arcane markup languages—you can build your own bridge.
5. The Ongoing Quest for Documentation That’s Both Accurate and Engaging
Too often we skip man pages and turn to blog posts or Stack Overflow, assuming the official docs will be dry or outdated. But my experience shows that man pages can be the best source of truth. Projects like Django have proven that documentation can be as good as a great tutorial while remaining 100% correct. The tcpdump and dig updates are a step in that direction. The key is to treat documentation as a first-class feature, subject to the same rigorous review as code. With the right examples and a user-friendly format, man pages can become the go-to resource—even for those of us who usually prefer a quick Google search.
Improving the man pages for tcpdump and dig was more than a documentation exercise—it was a chance to rethink how we share knowledge about essential tools. By focusing on basic examples, incorporating maintainer insights, and simplifying the authoring process, we can create resources that truly help people. Whether you’re a network engineer or a curious developer, I hope these lessons encourage you to give official documentation a second look. And if you ever need a quick tcpdump command, remember: -v -w is your friend.