Examples for the tcpdump and dig man pages
Julia Evans, a known advocate for practical developer tools, details her recent successful efforts to significantly improve the tcpdump and dig man pages by adding essential examples. This endeavor highlights a common pain point for many developers—the often-dreadful state of official documentation—and demonstrates a pragmatic path towards making fundamental tools more accessible and user-friendly. Her personal journey from documentation-skeptic to optimistic improver resonates deeply with those who've struggled with obscure man pages.
The Lowdown
Julia Evans outlines her project to enhance the official tcpdump and dig man pages by incorporating practical, beginner-friendly examples. This initiative stems from her belief that official documentation, when properly curated, can offer unparalleled accuracy and utility, serving as a reliable resource even for infrequent users.
- Core Goal: The primary aim was to add the most basic examples to help users who don't frequently use
tcpdumpordigquickly recall how to perform common tasks. - Motivation for Improvement: Evans emphasizes that man pages, through their review processes, can maintain near 100% accuracy and often contain undocumented but highly useful features, like
tcpdump -vfor live packet summaries. - Personal Shift: Initially skeptical of documentation, Evans now expresses optimism that official resources can be as good as high-quality blog posts, with the added benefit of being definitively correct.
- Technical Solution: To overcome the complexity of the
roffformatting language used for man pages, she developed a simple Markdown-to-roff conversion script, bypassing the need to learnroffdirectly and offering a flexible approach. - Behind-the-Scenes: The project also led her down a rabbit hole into the history of
roffand the cultural differences in documentation between BSD and Linux systems, hinting at a deeper dive into these topics in the future.
Evans' work serves as a testament to the idea that foundational technical documentation can be systematically improved, making powerful command-line tools more approachable and efficient for a wider audience.