Enhancing Man Pages with Practical Examples: A Deep Dive into Dig and Tcpdump

In the quest to make command-line tools more accessible, adding meaningful examples to man pages is a game-changer. This article explores the recent efforts to enrich the official documentation for dig and tcpdump by providing beginner-friendly examples, the motivations behind it, and the lessons learned from working with maintainers and the intricacies of roff formatting.

1. Why were examples added to the dig and tcpdump man pages?

The primary motivation was to address a common pain point for infrequent users: forgetting how to use a tool. While man pages are authoritative, they often lack practical, concise examples that illustrate common use cases. By adding examples, the goal was to bridge the gap between the man page’s exhaustive reference and the user’s immediate need for a quick command. The author observed that examples in man pages are highly valued, as they reduce the learning curve and encourage direct use of the tool. Moreover, it transformed the documentation from a daunting wall of text into a friendly guide. For tools like dig and tcpdump, which are powerful but complex, a few well-chosen examples can save time and frustration. This effort aligned with feedback from users who indicated that examples are among the most helpful parts of a man page. By focusing on beginners and those who use the tool sporadically, the new examples aim to cover the absolute basics without overwhelming the reader with edge cases.

Enhancing Man Pages with Practical Examples: A Deep Dive into Dig and Tcpdump

2. What kind of examples were added to the dig man page?

The dig man page examples cover fundamental DNS lookups that users commonly need. They include how to query a specific record type (like A, MX, or NS records), how to use +short to get a concise answer, and how to specify a different DNS server. For instance, one example shows dig @8.8.8.8 example.com A to query Google’s public DNS for an IPv4 address. Another demonstrates troubleshooting reverse DNS with dig -x 192.0.2.1. The examples also illustrate practical uses like checking the authoritative nameservers for a domain. Each command is accompanied by a brief explanation of what it does and why you might use it. The selection was based on the most common questions from support channels and Stack Overflow. The maintainer, Ondřej Surý, provided valuable insights into which flags are genuinely useful for everyday tasks. As a result, the examples avoid rare or outdated options, ensuring they remain relevant for current users of the tool.

3. How did the tcpdump man page examples improve?

The tcpdump man page received an update to its existing examples, expanding them to cover more basic but essential scenarios. New examples include how to capture traffic on a specific interface (tcpdump -i eth0), how to limit the number of packets (-c 10), and how to save packets to a file (-w out.pcap). A key addition is the use of -v during file saving to display a live packet count summary—a feature the author learned from maintainer Guy Harris during the review process. The examples also show how to apply BPF filters, such as capturing only HTTP traffic on port 80. Each example is written with the typical user in mind: someone who may not remember the syntax but needs to quickly capture specific traffic. The goal was to provide a “cheat sheet” feel, so users can copy the command and adapt it. The feedback from the review process was instrumental in ensuring these examples are not only correct but also demonstrate best practices, like using -nn to avoid DNS resolution delays.

4. How did maintainers contribute to the quality of these examples?

The review process involved maintainers like Denis Ovsienko (tcpdump) and Ondřej Surý (dig), who brought deep knowledge of the tools. They corrected inaccuracies, suggested more efficient commands, and highlighted features that even experienced users might overlook. For example, the -v flag with -w in tcpdump was a tip from Guy Harris that the author hadn’t considered. This collaboration ensured the examples reflect real-world usage and avoid common pitfalls, like forgetting to specify an interface. The maintainers also validated that the commands worked across different versions and platforms. Their involvement added credibility and replaced the author’s assumptions with verified facts. This process shifted the author’s perception of documentation: rather than being a stale reference, it became a living resource where maintainers willingly share their expertise. The experience was described as motivating and positive, reinforcing the value of community-driven documentation improvements.

5. What challenges did the author face while writing the man page for tcpdump?

The primary challenge was the man page’s formatting language, roff. The tcpdump project uses roff, which is notoriously difficult to write manually. The author did not want to learn it from scratch and instead created a simple Markdown-to-roff conversion script. This script used conventions already present in the existing man page to produce output that matched the style. Alternatives like pandoc were considered, but its output diverged significantly, so a custom solution was preferred. The script allowed the author to focus on content rather than syntax, but it was a “quick and dirty” approach. Despite this, the method worked well for the project’s needs. The author notes that this is not a long-term solution for every man page, but it demonstrates that even with complex tooling, it’s possible to improve documentation without becoming a roff expert. The experience highlighted the friction that current formatting systems create for contributors, suggesting a need for more user-friendly documentation tools in the open-source ecosystem.

6. What broader lessons can be learned from this documentation effort?

This project shows that man pages don’t have to be intimidating or inaccurate. With careful curation and maintainer involvement, they can be as helpful as a high-quality blog post—but with the added advantage of being authoritative. The key is to target infrequent users who benefit the most from clear, concise examples. The process also demonstrates the value of open collaboration: maintainers have unique insights into their tools, and users’ feedback drives improvement. The author felt optimistic about documentation’s potential, contrasting it with past reliance on unofficial sources like Stack Overflow. Additionally, the work underscores the importance of lowering barriers to contribute. By scripting a custom Markdown-to-roff converter, the author avoided a steep learning curve, making it easier to improve the docs. Finally, this effort shows that small, focused changes (like adding a few examples) can have a big impact on user experience. It encourages other maintainers to consider similar enhancements and reminds users that they can help shape the tools they rely on.

Tags: