The Diátaxis framework [1] provides a nice suggestion of different types of documentation, and when to use them. None of these types
is "best", each serves a different purpose.
Examples are the best documentation
21–30 of 179 posts
Re: Examples are the best documentation
#22You need both and there are no ways around that.
Examples let you grasp immediately how to use the library and provide you good starting point for your integration.
Detailed explanation of all params and configurations allows you to solve more complex problems and understand the full capabilities of the tool.
I am miserable when any of the two kind of documentation is missing.
The only exceptions are very simple libraries, where the example tells you already everything there is to know.
Re: Examples are the best documentation
#23tldr.sh is a project that had been doing this for man pages:
https://news.ycombinator.com/item?id=15779382
As the above 8y old discussion and today’s blog post both say: yes, examples are but one part of a complete set of learning materials — practicals, theory, recipes, reference.
However, in a toss up, the greatest of these is the one you always want first: picking the thing up, tossing it about to get a feel of it, and getting your hands dirty!
For code, worked examples are particularly helpful because your dev environment can jump to the function definition, which typically has its own reference documentation.
Re: Examples are the best documentation
#24Examples are best only for the beginner/occasional users. For more experience devs, you want regular docs, with full parameter list. Case in point: requests. Google always drops me to the pages like Quickstart[0], which are full of examples. But they are useless for advanced users! Yes, even my limited brain can remember that you call "get" to issue HTTP GET. What other options does it take? Does it take a timeout? H…
A proper doc definitely has to provide the details. However starting with an example or two is a nice way to a give the users a quick overview. Even better when this example is interactive as for redis where you even have an example use case. See https://redis.io/docs/latest/commands/incr/
Re: Examples are the best documentation
#25Examples are the best `quick start` documentation.
Comprehensive manuals/references are the best documemtation.
Re: Examples are the best documentation
#26when possible (python, golang and many others) I just go and read the source..
Re: Examples are the best documentation
#27Radical opinion: If the technical spec of a method cannot be intuited from the signature and a handful of canonical examples of usage, the method is probably trying to do too many things.
In particular, I don't want to have to learn half a dozen footguns because of a leaky abstraction.
Re: Examples are the best documentation
#28Similarly, unix man pages desperately need examples. They are almost without fail written as an exhaustive reference for someone who already knows how to use the tool, which is a totally valid use case. But that means they're generally useless for someone trying to use a tool for the first time. Good documentation needs to have both.
Re: Examples are the best documentation
#29Even better if the documentation examples are part of the test suite!
Re: Examples are the best documentation
#30Examples are best only for the beginner/occasional users. For more experience devs, you want regular docs, with full parameter list. Case in point: requests. Google always drops me to the pages like Quickstart[0], which are full of examples. But they are useless for advanced users! Yes, even my limited brain can remember that you call "get" to issue HTTP GET. What other options does it take? Does it take a timeout? H…
They're not mutually exclusive you know, you can have both example and a proper technical doc.