Revolutionizing Network Troubleshooting: Tcpdump and Dig Man Pages Now Include Beginner Examples

Breaking: Tcpdump and Dig Man Pages Get New Example Sections

September 2023 — Developers have added comprehensive, beginner-friendly example sections to the official man pages of two essential network troubleshooting tools: tcpdump and dig. The update targets users who rely on these tools infrequently or are completely new to packet analysis and DNS queries.

"The goal was to give the absolute most basic examples for people who use these tools infrequently or have never used them before," said the contributor behind the changes. "We want users to get up and running without needing to search for blog posts or Stack Overflow answers."

Background: Why Man Pages Needed Examples

The initiative began last month when the contributor noted that examples in man pages are extremely valuable but often missing. "My big takeaway was that examples in man pages are really great," they recalled. Traditional man pages assume advanced expertise, leaving beginners hunting for tutorials.

By adding simple use cases, the new examples bridge that gap. For instance, one newly documented tip: when saving packets with tcpdump -w out.pcap, adding the -v flag prints a live packet count summary — a feature the contributor said they never would have discovered alone.

What This Means for Network Professionals and Beginners

For infrequent users, the update reduces reliance on third-party resources. "Even with basic questions like 'what are the most commonly used tcpdump flags,' maintainers shared insights I never would have found on my own," the contributor explained. The official documentation now becomes a one-stop, accurate guide.

This change also signals a shift in documentation philosophy. "Maybe documentation doesn't have to be bad," the contributor said. "Maybe it could be as good as reading a great blog post, but actually correct." They pointed to the Django documentation as a model of clarity and accuracy.

Implementation: Avoiding the Complexity of Roff

Instead of learning the complex roff language used by man pages, the contributor built a custom Markdown-to-roff converter. "I didn't want to learn roff — I just wanted to write examples in Markdown and convert them automatically," they said. The converter followed existing conventions to ensure consistency.

While tools like pandoc were considered, the output was too dissimilar, prompting a dedicated script. The effort paid off: the new examples are now integrated without burdening contributors with arcane formatting.

Key Contributors to the Update

• Denis Ovsienko
• Guy Harris
• Ondřej Surý

"Thanks to the maintainers who reviewed the changes — it was a good experience and left me motivated to improve more man pages," the contributor added. The collaborative review process ensured accuracy and revealed hidden features.

Looking Forward: A New Standard for Documentation?

This effort could inspire similar improvements across other open-source tools. "Man pages can actually have close to 100% accurate information — going through a review process to ensure truth has huge value," the contributor emphasized. They hope this approach becomes more common.

The updated man pages for dig and tcpdump are now live in their respective package repositories, setting a precedent for accessible, reliable documentation in the networking community.