Latest Update to Man Pages Makes Network Tools More Accessible
In a significant move to improve developer and system administrator documentation, the man pages for two essential network diagnostic tools—dig and tcpdump—have been expanded with new, practical examples. The updates aim to lower the barrier for infrequent users and beginners.
“The goal was to give the absolute most basic examples for people who use these tools infrequently or have never used them before,” said a project contributor involved in the revisions. “We wanted to show how to actually get started, not just list every option.”
The changes come after widespread feedback from the open-source community and were reviewed by maintainers including Denis Ovsienko, Guy Harris, and Ondřej Surý.
Background: Why Man Page Improvements Matter
Man pages are the traditional Unix method for documenting command-line tools, but many users find them dense and difficult to read. While they are often 100% accurate, they rarely include step-by-step examples—a gap that blog posts and Stack Overflow have long filled.
The maintainers of dig and tcpdump recognized that adding real-world usage examples would help users solve common problems without leaving the terminal. The new sections focus on the most frequently used flags and workflows.
For instance, a common task like saving captured packets to a file now includes a pro tip: “Use tcpdump -w out.pcap -v to print a live summary of how many packets have been captured so far,” said one developer. “I didn’t know that until I worked on these examples.”
What This Means for Network Administrators and Developers
This shift toward practical documentation could change how users interact with man pages. Instead of searching for external tutorials, they can now find immediate, reliable guidance within the official documentation.
“I always used to skip man pages and read a blog post or ask a friend,” admitted the same contributor. “But maybe documentation doesn't have to be bad. It could be as good as a great blog post—and actually correct.”
The project also tackled the technical challenge of writing in the roff language used by many man pages. Instead of learning roff, the team created a custom Markdown-to-roff script to streamline the process. This approach may serve as a template for other projects looking to improve their documentation.
Key Details of the Update
- dig man page: Now includes basic query examples, such as looking up DNS records for a domain.
- tcpdump man page: Expanded examples covering packet capture, filtering, and saving to files.
- Community review: Changes were iterated with help from experienced network tool maintainers.
The updates are already live in the latest release of the tools. Users can view them by typing man dig or man tcpdump after updating their packages.
Future Outlook: A New Standard for Man Pages?
While this is a focused improvement, it raises the question of whether other command-line tools will follow suit. The project contributor said they are motivated to continue working on documentation.
“Even for basic questions like ‘what are the most commonly used tcpdump flags,’ maintainers often know useful features you’d never discover alone,” they explained. “Going through a review process ensures the information is not just helpful but true.”
The addition of examples to the dig and tcpdump man pages marks a small but meaningful step toward making official documentation more user-friendly—without sacrificing accuracy.