FRESH

Hacker News

Examples for the tcpdump and dig man pages

95 points by ibobev

by stainlu

0 subcomment

The reason man pages historically lack examples isn't laziness -- it's that examples have a different maintenance burden than reference text. Flag descriptions are stable: -v means verbose today and will mean verbose in a decade. But a tcpdump example capturing HTTP traffic on port 80 quietly becomes misleading when everything moves to TLS on 443. A dig example querying a specific record type assumes the reader has a domain with that record configured.
Julia Evans' approach works because she maintains the examples actively. The challenge for upstream man pages is that nobody wants to own the ongoing maintenance of examples that can silently go stale in ways that flag documentation doesn't. tldr-pages solved this with community maintenance, but it's a separate project rather than integrated into the man page itself -- which means you need to know tldr exists before you benefit from it.

by mccanne

0 subcomment

Hey really cool! Tcpdump co-author here. If you're interested in the origin story of the tcpdump language, bpf, and pcap, I had fun putting together a talk a number of years ago... https://www.youtube.com/watch?v=XHlqIqPvKw8

by loudmax

1 subcomments

For normal, day to day use, examples in documentation is absolute gold. As a practical matter, that's how we human learn to do things. Perhaps surprisingly, even AI benefits from examples.
Children don't learn to speak a language by learning all the grammar and conjugation rules first. They learn by repeating phrases they've heard before and they generalize. Usually we learn tools the same way. We see someone else using a tool, and we do what they're doing, and generalize.
That's not to say that man pages should consist only of examples. There are times when you really do need to understand how the tool processes corner cases and really understand how it works. But I expect most of us here can relate to the experience of opening the man page for a tool and being completely baffled by a wall of unfamiliar jargon. Most of the time you just want to see how to do the most normal common functions, especially when you're learning a tool the first time.

by teleforce

0 subcomment

by drob518

2 subcomments

A simple Markdown to roff translator seems like an ideal project for an AI to tackle.

by stephenlf

2 subcomments

My go-to for examples is ‘tldr’ Maybe you could add the examples there, too? Then again, if every man page had basic usage examples, maybe I wouldn’t go to ‘tldr’