Enhancing Man Pages with Practical Examples: Insights from tcpdump and dig
Man pages have long been the go‑to reference for command‑line tools, but they often lack the practical examples that new and occasional users crave. This Q&A explores the recent initiative to add clear, beginner‑friendly examples to the man pages of tcpdump and dig — two powerful networking utilities. Below, we dive into the motivation behind the effort, the surprising lessons learned from maintainers, and the creative workaround used to bypass the arcane roff language. These insights show that official documentation can be both accurate and approachable, much like a great blog post. Jump to the first question to see why examples matter so much.
What sparked the initiative to improve the tcpdump and dig man pages by adding examples?
The idea grew out of a broader reflection on what makes man pages truly helpful. The author had noticed that examples are frequently the most valued part of any documentation — they immediately show how a tool works in real use. Both tcpdump and dig are essential for network troubleshooting, yet their official man pages contained very few, if any, practical examples. After discussing with colleagues and maintainers, it became clear that adding a dedicated examples section would fill a major gap, especially for infrequent users who forget command syntax. The goal was not to be exhaustive, but to cover the most common use cases in a straightforward way. With support from the maintainers (including Denis Ovsienko, Guy Harris, and Ondřej Surý), the author drafted new content, which then underwent thorough review to ensure accuracy.
What was the primary goal for the new examples sections?
The main objective was to create the simplest possible examples for absolute beginners. The author wanted to answer questions like: “How do I capture packets on an interface?” or “How do I look up an A record for a domain?” — without assuming any prior knowledge. Each example avoids jargon and explains what the command does step‑by‑step. For instance, the tcpdump examples show how to capture traffic to a file (-w out.pcap) and later how to read that file. The dig examples illustrate basic lookups with and without specific record types. By keeping the examples minimal and self‑contained, even someone who has never used the tool can quickly get started. The feedback from early readers confirmed that this approach successfully lowers the barrier to entry.
How do examples in man pages benefit infrequent or new users?
Infrequent users — those who might use tcpdump or dig only once every few months — often struggle to remember command‑line options or flag combinations. Rather than re‑reading the entire man page (which can be dense), a well‑crafted example immediately refreshes their memory. Examples also demonstrate best practices that aren’t obvious from flag descriptions alone. For instance, while working on the tcpdump examples, the author learned that combining -w with -v prints a live packet count — a tip that saved time during long captures. New users, meanwhile, benefit from seeing the tool in action before diving into the theory. The examples act as a quick start guide, making the man page less intimidating and more approachable. This shift from “reference manual” to “tutorial” helps both groups achieve their goals faster.
What surprising discovery did the author make while writing the tcpdump examples?
While reviewing the tcpdump man page for possible examples, the author noticed that the -v flag is often used for verbose output, but its interaction with -w (write to file) was less known. Normally, -w suppresses all output to the screen. However, when combined with -v, tcpdump prints a periodic count of packets captured so far — right on the terminal. This live progress indicator is incredibly useful for long captures, as it confirms the tool is still running and gives a rough idea of traffic volume. The author had never encountered this feature in blog posts or Stack Overflow answers. It underscores a key advantage of working directly with official documentation: maintainers can point out hidden gems that even experienced users may miss. Without this collaboration, the examples would have omitted a genuinely helpful tip.
Why is it valuable to invest in official documentation rather than relying solely on third‑party sources?
Third‑party sources like blog posts and forums often contain outdated or inaccurate information. Man pages, by contrast, go through a formal review process that ensures near‑100% accuracy. When developers take the time to improve man pages, they create a single source of truth that users can trust. The author notes that maintainers often know the tool inside out and can flag common mistakes or promote underused features. For example, during the dig examples review, Ondřej Surý suggested including the +short option to produce cleaner output — a small tweak that many users overlook. By investing in official docs, the community gains a reliable reference that doesn’t require cross‑checking multiple sources. This is especially critical for security‑sensitive tools like tcpdump, where incorrect usage could lead to data loss or misinterpretation of network traffic.
How did the author handle the challenge of writing in the roff language?
The tcpdump man page is written in roff, a markup language that is notoriously difficult to read and write. Rather than learning roff from scratch, the author wrote a minimal Markdown‑to‑roff conversion script. This approach allowed them to draft the examples in familiar Markdown and then automatically transform them into the required roff format. The script reused existing conventions from the man page (such as macro names) to stay consistent. Although tools like pandoc exist, the author found that their output differed significantly from the man page’s style, so a custom script was more appropriate. This workaround made the writing process faster and less error‑prone, proving that one doesn’t need to master a legacy language to contribute meaningful improvements to documentation.
What overall lesson did the author learn from this man‑page improvement project?
The project changed the author’s perception of documentation: it doesn’t have to be dry or incomprehensible. By focusing on concrete examples, listening to maintainers, and being willing to experiment (like writing a custom conversion script), the author produced content that is both accurate and user‑friendly. The positive feedback from the community — and the satisfaction of seeing the examples help others — motivated further work on man pages. The author now believes that official documentation can be as engaging and helpful as the best blog posts, with the added benefit of being formally verified. This experience suggests that even small contributions, like adding a few well‑chosen examples, can significantly enhance the usability of essential tools.