Summary

Julia Evans contributed examples sections to the official man pages for tcpdump and dig, motivated by her earlier writing about how examples make man pages more useful. Her goal was to provide the most basic, beginner-friendly examples for infrequent users who don't remember how the tools work. She found the process rewarding and collaborative, learning new things from maintainers along the way. The experience shifted her perspective on official documentation, making her cautiously optimistic that it could be as useful as blog posts while being more accurate. She also wrote a custom markdown-to-roff converter to avoid learning the roff language directly.

Key Insight

Contributing examples to official man pages is a high-leverage way to improve documentation accuracy and accessibility, because the review process guarantees correctness in a way blog posts never can.

Spicy Quotes (click to share)

• 7

  Maybe the documentation doesn't have to be bad? Maybe it could be just as good as reading a really great blog post, but with the benefit of also being actually correct?

• 5

  Man pages can actually have close to 100% accurate information! Going through a review process to make sure that the information is actually true has a lot of value.

• 6

  I always kind of assume documentation is going to be hard to read, and I usually just skip it and read a blog post or Stack Overflow comment or ask a friend instead.

• 2

  Even with basic questions 'what are the most commonly used tcpdump flags', often maintainers are aware of useful features that I'm not!

• 2

  I went on a whole rabbit hole learning about the history of roff, how it's evolved since the 70s, and who's working on it today.

Tone

enthusiastic, reflective, optimistic