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
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.
I’ve looked at that a bit. Roff and mandoc etc have specialized tagging that’s not easily representable in markdown. You’d wind up with a lot of boilerplate or special non-standard markup, which would undermine the point.
The LLMs are super good at doing that translation, though. They can write those formats no problem.
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’
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
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.
A simple Markdown to roff translator seems like an ideal project for an AI to tackle.
I’ve looked at that a bit. Roff and mandoc etc have specialized tagging that’s not easily representable in markdown. You’d wind up with a lot of boilerplate or special non-standard markup, which would undermine the point.
The LLMs are super good at doing that translation, though. They can write those formats no problem.
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’
It's a bit weird to see someone doing free work for the community and then ask them to do even more free work.
I also like: