IMHO, not just an "example", but a dead-simple example. Just show me the absolute bare minimum of what I need to do to get this working, and I can take it from there. It really doesn't help me when you build a book store from the ground up when I am only trying to learn a specific part.
Examples are the best documentation
91–100 of 179 posts
Re: Examples are the best documentation
#92Even better if the documentation examples are part of the test suite!
Right, one of the best out-of-box tooling decisions for Rust is that by default, and out of the box cargo will assume all your documentation examples are tests it should compile and execute. This means so long as you run the tests before shipping you basically can't ship with examples you forgot to update after an API change because they either don't compile or don't work. And you might think well, nobody would ship…
I'd go a bit further and say that all tests are documentation examples. Rust is nice because it has symmetry and documentation examples are tests.
Re: Examples are the best documentation
#93Earlier quoted context omitted.
Examples are often crucially valuable, not just for beginners. Some of them can inject in five seconds an understanding equivalent to an hour of reading the very-objective docs and experimenting. I'm thinking of some git doc pages. But it applies just as well to single functions that are very simple conceptually, but hard to describe clearly and briefly and completely. The developer has time for neither or both. Once…
[flagged]
>Examples is for beginners.
No, not really, or I should say simple examples are for beginners.
Typically when I'm writing example pages I write it in
Simple example
Simple example
Simple example
Intermediate example
Intermediate example
Complex example.
Having complex examples can really help those that are looking at going beyond the basics.
Re: Examples are the best documentation
#94The "Real" documentation is the implementation. Prioritize making the source code available and understandable.
Examples are very nice. One way to create examples is with test cases. Test cases can also be packaged with source code!
Re: Examples are the best documentation
#95Similarly, 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 .
This. I do not know how many people are disappointed at their initial contact with Unix/Linux because they hit a complicated man page while trying to use a command
Re: Examples are the best documentation
#96Similarly, 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 .
I liked it when Stackoverflow did something similar.
https://stackoverflow.com/documentation
We have shut down Stack Overflow Documentation. Documentation was our attempt at improving existing reference materials by focusing on examples. The beta ran from July 21st, 2016 until August 8th, 2017. For more details on why we ended it, please see our post on meta. Thank you to everyone that participated. As always, the content contributed by our community is available under CC BY-SA.
Re: Examples are the best documentation
#97The 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. [1] https://diataxis.fr/
Absolutely! Examples (or 'tutorials') are just one quadrant of education about a system.
Not sure who came up with it first, but your link is similar to the author's link at the conclusion of the article:
> Since even major software projects rarely offer [4 distinct kinds of documentation][1], I am often hesitant to click on a "Documentation" link
Personally, I prefer documentation written as an explanation. If I understand how the thing works or why it's done that way, everything else is easy. Examples/tutorials/how-to guides only help me develop a conceptual framework by experiencing it, and I know that's how some people learn, but a skilled technical writer or educator can help me generate that conceptual framework correctly the first time.
I think the reason API references are so common is that they're really best suited for someone trying to build a wrapper or fully-compatible alternative implementation...which is what the original authors were doing, before the project existed. Many projects started as an internal, private API reference, and generating documentation can be as easy as making that public.
Re: Examples are the best documentation
#98Documentation is often wrong, incomplete, poorly written.
If you only have N hours to work on "documentation", I say spend it on examples.
Also AI can probably turn a quality example into a doc whereas it can't turn a doc into a quality example.
Another thing to contemplate. I stand here as a 75 kilo entity - an example. I am, IHMO, a good example. The documentation on this example is so far many millions of page long, is very incomplete, certainly wrong, and could not be used to create said example.
Re: Examples are the best documentation
#99Please don't follow this advice! The best thing about old school Python was that I could reliably pull up the documentation for a library and it would clearly list the arguments and return values for each function. Now when I look at the documentation for many JavaScript, and even Python, libraries it's just examples. That's great if I'm trying to just throw something together as quickly as possible, but not if I nee…
This is the right answer. Everyone who disagrees with you are amateurs.
A Javadoc-esque API doc is the minimum requirement for a serious language/library. Examples and tutorials are nice too, but the API doc can be automatically generated in every serious language so not having it is just plain unacceptable.
Tutorials, articles and examples etc are fine too, they can be combined with the API doc like Java does. But that's gravy, on top. You don't have just gravy, it needs to be on top of something and that something is a proper API doc.
This isn't even a discussion in my mind, it's just the right way to do it. It's a solved problem. You optimize for power users not amateurs. 99% of the time when I look up docs what I need is a plain boring API doc, I only need examples in my first week.
Re: Examples are the best documentation
#100Please don't follow this advice! The best thing about old school Python was that I could reliably pull up the documentation for a library and it would clearly list the arguments and return values for each function. Now when I look at the documentation for many JavaScript, and even Python, libraries it's just examples. That's great if I'm trying to just throw something together as quickly as possible, but not if I nee…
Personally - what you're asking for is type definitions. And it's a blurry line, since type definitions are a good form of documentation. It's just that type-system tooling has mostly replaced the need to go read through the docs for that. I expect to get it easily and obviously in whatever editor or IDE I've configured. I think the prevalence of example based documentation is because of this trend - don't waste time…
Very often before installing or using a library I want to look at functions and their parameters to understand how and if I can use it as I intend