How Practical Examples Transformed the tcpdump and dig Man Pages

By ● min read

<article> <h2 id="introduction">Introduction</h2> <p>Man pages have long been the cornerstone of Unix and Linux documentation, yet many users find them dense and difficult to navigate. Recognizing this, a contributor recently undertook the task of improving two beloved networking tools—<strong>tcpdump</strong> and <strong>dig</strong>—by adding practical, beginner-friendly examples to their man pages. The result is a more approachable resource that benefits both new users and those who only occasionally use these tools.</p><figure style="margin:20px 0"><img src="https://picsum.photos/seed/3866337113/800/450" alt="How Practical Examples Transformed the tcpdump and dig Man Pages" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px"></figcaption></figure> <h2 id="value-of-examples">The Value of Examples in Man Pages</h2> <p>Examples serve as a bridge between abstract documentation and real-world usage. For infrequent users of <strong>tcpdump</strong> or <strong>dig</strong>, remembering syntax or common flags can be a challenge. By including clear, concise examples, the man page becomes a quick reference guide rather than a cryptic manual. This approach aligns with what many users have expressed: they want documentation that is accurate, concise, and immediately useful.</p> <h2 id="improvements-to-dig-and-tcpdump">Improvements to dig and tcpdump Man Pages</h2> <p>The <em>dig</em> man page now includes a dedicated examples section, while the <em>tcpdump</em> man page’s examples have been updated and expanded. These additions were designed to cover the most basic use cases, such as performing a simple DNS lookup with dig or capturing packets on an interface with tcpdump. The goal was to provide a gentle on-ramp for beginners without overwhelming them.</p> <h3 id="goals-for-beginners">Goals for Beginners and Infrequent Users</h3> <p>The primary objective was to address the needs of two groups: those who have never used the tool and those who use it sporadically and may forget the syntax. For example, a typical tcpdump example might show how to capture traffic on a specific interface with <code>-i eth0</code> and save it to a file using <code>-w output.pcap</code>. Similarly, a dig example could demonstrate querying a domain’s A record with <code>dig example.com</code>. These straightforward examples were carefully chosen to be immediately applicable.</p> <h2 id="why-improve-official-documentation">Why Improve Official Documentation?</h2> <p>There are several compelling reasons to invest in man page improvements:</p> <ul> <li><strong>Accuracy</strong>: Man pages can achieve near-100% correctness when maintained properly, unlike blog posts or Stack Overflow answers that may become outdated.</li> <li><strong>Review Process</strong>: Contributing changes goes through a rigorous review by tool maintainers, such as <strong>Denis Ovsienko</strong>, <strong>Guy Harris</strong>, and <strong>Ondřej Surý</strong>. This ensures that every example is not only helpful but also technically accurate.</li> <li><strong>Discovering Hidden Features</strong>: During the review, the contributor learned valuable tips. For instance, when using <code>tcpdump -w out.pcap</code>, adding the <code>-v</code> flag prints a live summary of captured packets, a feature unknown to many users.</li> </ul> <p>The collaborative process also reveals that maintainers are aware of lesser-known but extremely useful flags and options. By incorporating this knowledge into examples, the documentation becomes richer than any single user could create alone.</p> <h2 id="lessons-learned">Lessons Learned from the Experience</h2> <p>The contributor noted that working on official documentation was surprisingly rewarding. Many developers avoid man pages because they expect poor readability, but this project proved that well-crafted documentation can rival the best blog posts. Citing the <strong>Django documentation</strong> as an exemplar, the contributor expressed optimism that man pages can be both engaging and trustworthy.</p> <p>One of the biggest challenges was the technical format. The <em>tcpdump</em> man page is written in the <strong>roff language</strong>, which is notoriously difficult to work with. Rather than learning roff from scratch, the contributor wrote a simple <strong>Markdown-to-roff script</strong> that converted basic Markdown into roff. Although tools like <em>pandoc</em> exist, its output was too different from the existing style, so the custom approach was chosen. This solution allowed the contributor to focus on content rather than formatting.</p> <h2 id="conclusion">Conclusion</h2> <p>Adding practical examples to the man pages of <strong>tcpdump</strong> and <strong>dig</strong> has made these essential tools more accessible. The experience demonstrates that investing in official documentation pays off, both for users and for the open-source community. With proper examples, even the most intimidating man page can become a friendly guide.</p> <p>For those interested in the final results, you can view the updated <a href="https://man.openbsd.org/dig">dig man page</a> and <a href="https://man.openbsd.org/tcpdump">tcpdump man page</a> (examples sections). The contribution process also inspired further work on other man pages, proving that a small change can have a large impact.</p> </article>