Please 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 need to fix a problem or actually learn the library.
Also having examples is fine, but they should be considered a bonus; not documentation.
Both are needed for good documentation. You start with the details and then finish with a few examples so that someone who has read the details can check their understanding. Sometimes the example is all you need, but most often there are far more possible combinations of options such that an example of all the useful ones would be several books long (there is no good way to sort/index them so someone wouldn't find the example they need if you wrote them all). So you start with an explanation of each option, and then a few examples that are as different as you can make them so readers get a sense of what is possible and can look back to the explanation to figure out the changes they need to get the example to do what they need.
Good documentation is hard, and very rare these days.
Documentation is like the system it supports too: the only unchanging ones are those nobody is using! I think this is obvious when we compare quality between the historically much slow manual releases with the cadence today, and the documentation of relatively slowly changing projects with newer, faster ones.
It's a lot of work to create good documentation; it's even more work to keep it good.
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 manually writing the same thing type tooling is going to give your users anyway.
When I hit docs - I'm much less interested in the specific arguments, and I'm very interested in "Capabilities": Problems this tool can solve.
Examples are a great showcase for that. Especially if I have a specific problem in mind and I just want to know if a "tool" can solve that problem, and how to use it to do so.
---
If I have a type system: I want examples first.
If I don't have a type system: 1) I'm not happy. 2) I want examples first, followed by the detailed arguments/return/data structure docs you're referring to.
It's the API specification. It's not just the functions and their parameters, it's also an explanation of what they do.
> I'm much less interested in the specific arguments, and I'm very interested in "Capabilities"
And that's exactly what an API specification provides you, and that examples do not. Examples only tell you how to use the API on the same way that the author is using it.
I really want both. I can follow examples and read specifications, but i likely want the simplest example first if I'm using a tool, and then the specifications after i've used it a few times.
it's much harder to imagine everything a tool can do with only the specs, and I'm not clear what things I'm missing. Examples make it concrete
The most annoying problem I run into with strongly typed languages or even typed python for that matter, is what on earth do I expect this to return?
With python, it could be a mysterious class that isn't explicitly mentioned.
For Rust, you often need to know 4 layers deep of nested types for various error and flow control, and once generics are introduced with the expectation of implemented traits, it all goes out the window.
If I need to declare the type of a value ahead of time, or know it's shape to serialize, check, etc, I want a very clear "this is what it returns, this is how it's expected to be used".
I don’t fully agree. Javadoc style documentation should be programmatic and driven by types and inline doc strings. It should just always exist and I would argue having it online is ok but why would not just go to the code itself.
Examples like QuickStart guides should absolutely be required. They serve as the quick entry point and general use of the library. If I only had the code docs I would have no idea how I am supposed to use the api and was my main complaint of many Java libraries historically as they only had a Javadoc.
I think this is almost provably true, for the simple reason that detailed technical documentation can be a substitute for examples, but the reverse isn't true.
1. If you want an example and the docs have an example, great.
2. If you want technical details and the docs have technical details, great.
3. If you want an example but the docs only have technical details, you can still get what you want by spending longer to read and understand the documentation. It's inefficient but it works. Third party examples are also frequently available.
4. If you want technical details but the docs only have examples, you're SOL. You have to hope that the code is available and readable, or just try stuff and hope it works. Third party technical details are rare.
I'm not sure it's inefficient. It gives you the knowledge what is and isn't possible and also the semantics of what you actually do, all things you need to have later anyway. Relying only on examples is a great way to miss unintended side-effects or other consequences.
The first part of that line is "If you want an example...". If you want to learn about more advanced usage of some function, then you don't want an example, and that line doesn't apply to you.
Did you stop to consider that perhaps other people learn differently than you, and find examples as a way to soften the friction that context switching causes in a job?
I don't understand the resistance to examples being a part of documentation (and not a bonus).
I think you're being unfair. The blog post claimed "Examples are the best documentation". If I use your own logic, shouldn't I say to the blog writer "Haven't you ever thought people learn differently from you?".
I think harimau777 was just expressing his opinion, like the blog owner.
It shouldn't be an either/or situation. Good documentation should include both the API spec _and_ examples. I believe the person you're replying to was complaining about documentation that's _only_ examples since it seems like that's what TFA was advocating for.
There's a neat mental model that there are four kinds of documentation: tutorials, how-to guides, explanation, and reference.
I think that examples fit into the first or the second kind; I'm not too concerned which category they belong to, because the point is that all kinds all have their place.
Source: https://docs.divio.com/documentation-system/ - someone has already linked it in another comment, but I think it's worth replying because the comments in this thread are arguing about which kind they like the most.
To me, you're describing a specification, a type of documentation, with examples being another type. And I agree that a specification should just list definitions with explanations.
But there's no reason that a document cannot contain both a specification and examples. That's the type I prefer, and that's the type I mostly encounter nowadays. Usually a specification on the left with some examples on the right, maybe even interactive examples.
I used to work on Drupal sites and they have very few examples for how to actually use various functions. So you'd run into instances where you're doing something completely wrong even if the function name makes sense.
The best documentation is type references and examples and a line explaining what the function does. Not one or the other.
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.
Sure, but you can optimize for one without excluding the other. Adding examples _allows_ amateurs to gain experience and _become_ power user, and imposes near-zero cost on power users who can just skip a couple lines and get into the "real" API doc.
That's not what anyone said. We both said examples are great. They're just not more important than proper API docs.
They're not the best. The best is thorough api docs. The rest is nice to have.
And I'm not no true scotsmaning, I'm just saying most devs are ass. I know, I see people with 20 years of experience on me write buggy trash code that I have to fix. I see people whine about the java docs as if they aren't some of the best damn docs available anywhere. Because they're ass and they can't properly use the tools they're given. They'd rather have examples and copy snippets from SO or have ChatGPT write it for them.
Any professional will appreciate proper documentation. It is literally impossible to create examples for every situation. Api docs, by their nature, cover all use cases because they simply describe what exists not how to use it. So for those of us with the knowledge and intelligence to actually just look at the parts and put them together on our own, ie professionals, API docs are king. Examples are useful sometime, API docs are useful all the time.
But of course if you don't even know the language well enough to read the documentation, you prefer examples.
I think it's a bit harsh to call everyone who disagrees amateur. However, anecdotally it doesn't feel very incorrect. When I do pair programming with less-experienced developers, I'll often watch them glance at the API docs, skim over the technical details, look at the example, copy paste it, and then be confused why it doesn't work. Then I pointedly suggest reading the specific paragraph that explains the confusion they have.
Yeah, I'm not saying it to be mean I'm just calling it as I see it. Can't recall if it was the article or a comment or both, but someone mentioned that it's hard to understand API docs in some cases because it relies on understanding the language itself.
If you don't even know the language well enough to read docs I'd say you're an amateur. And if you're one of those people who just chronically don't read docs you're definitely an amateur. I mean you may have a job and you may even build stuff that kind of works, but unless you're sitting down and looking closely at the details you're not doing things right. You can't be. Doing things right requires looking closely at the details.
And I know from experience that there's a vast number of employed amateurs who write nothing but legacy code.
Now, languages with common / short names? All the time. Go, C, C++, D, etc; even Rust (especially since all the libraries have similarly ambiguous names related to iron oxide).
For C there is excellent documentation and tutorials in man pages and info documents. It's in my experience the best you can find short of reading the code yourself.
In DuckDuckGo you should be using !py rstrip, that's what the bangs are for. But yes, in general most of the good (third-party) python resources have been killed by SEO spam.
Examples 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? How do I pass in content-type? Does raise_for_status ignore 204?
Both have their merits, but if developer only has time for one, I'd go for proper doc.
It is order of magnitudes easier to understand behavior through examples than through a reference-like documentation. People suck at naming things, and then documenting them. Just today I spent the last few hours trying to figure out how to get something to work because a parameter only worked if another paramter had a specific value. There was too much magic to try and figure out the code, llms wrongfully told me the latest version doesnt support the parameter because it couldn't find any documentation.
Ultimately, creating a small example that I know should've worked and changing things in a way that I could narrow down the problem worked best.
The point to all this is that examples often encapsulate multiple things into a condensed format, that is extremely high fidelity (since it's typically a code example that runs and has output). Things like Api documentation in comparison typically cover a huge surface area, and have way less effort in maintaining them.
Also for the record, I absolutely don't trust libraries on behavior that isn't extremely obvious, explicit and so absolute that it's almost effortless to find out (I am talking first thing on README, entire sections showing that one thing, or definition through types). I just assume that things like behavior around status codes are going to change, and do my best in the calling code to mitigate issues as much as possible.
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 the productivity barrier for one has been broken, the other is a tiny extra effort. In that case, they must provide both, except in the small minority of cases that are exceptionally self-describing, where one (usually docs) is sufficient.
The number of times I’ve opened FFmpegs man page must number in the hundreds. I think I’m a pretty good conceptually, but I can’t remember all the flags. IE that –s is frame size, while -fs is file size.
And while that man page does have some examples, these days I tend to ask an LLM (or if it’s going to be simple Google) for an example.
That's why the recommended practice with shell usage is to write a script (or alias or function) and to use the long version of the flag in the script. Instead of having a complex invocation of ffmpeg, you'd have `flac2mp3 -q low file`.
>When jumping between projects, languages and frameworks, it takes a considerable amount of mental energy to restore the context and understand what is going on.
Of course we want a full list of public functions with all the info. But with just a list of functions it's often still not quite clear how you're supposed to setup and call them, unless you dig through the whole list and try to understand how they interact internally. A few short examples on "How do I init the library/framework so I can start using it", "How do I recover from a failure case", etc. makes the docs infinitely more accessible and useful!
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/
Unfair example google has the worst docs in existence. Either a quickstart with one uselessly simplistic example or an autogenerated class list on a totally separate site with no explanations to be found. Often I just end up looking at their libraries source code to learn how to use it.
Similarly, 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 haven't had that problem. I just code something up, and poke around to understand some of the terms that it's talking about. Then I start reading about error return codes, why them happen, what kinds of parameters actually mean, etc. No examples are usually needed as long as documentation is complete
The most frustrating things are things that are undocumented at all and only have examples. What the hell kind of shitty documentation is just examples with no idea what parameters could or shouldn't be?!
Sometimes, I just wanna remind myself how to use xargs for some command text replacement in a random one-liner on the terminal.
If I tried to do that with man... I'd have to read (in alphabetical order) the documentation for 6 different command flags. That's how far I'd go to read about the flag -- to actually use it, I'd have to experiment with the command flag until I figured out the actual syntax using my imagination.
Let's say instead that I am in a rush... so I'm skipping that time-consuming process and instead scrolling furhter down for some practical examples... one full page later I find a bunch! ... Except there's only 4 and none of them demonstrate what I need (the syntax is completely different). The docs wasted my time exactly when I most needed it NOT to do that. If I'd instead just googled "xargs replacement example", I would have gotten something I can copy/paste in seconds and could have gotten on with my life!
The moral of the story is this: Don't tell without showing. Don't show without telling. Do both if your goal is to be understood.
Once you have something working the way you like, make your own example and put it on a github repo named "today-i-learned". Then you can refer to it as your own documentation for yourself.
I wholeheartedly agree, and would like to remind all man page authors that there’s even a conventional section named EXAMPLE. See man(1) for details. [0]
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.
The state of man pages in the GNU + Linux ecosystem is just atrocious in general. You can thank the GNU Project for that. In sane man pages that actually care about quality, examples are specified where appropriate: https://man.openbsd.org/apropos.1#EXAMPLES
The GNU project choose to separate documentation into reference (man pages) and tutorials and prose (info). It works quite well and in my opinion info is also superior since it is an interactive hypertext system. So you can have cross-references, outlines, alternatives for different audiences, etc. .
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
When feasible, I'd add repl environments. The ability to quickly modify and test the example can make up for a lot of the shortcomings documentation might have.
I'm honestly surprised there are people who think that only examples are fine. And I'm equally surprised there are people who think only reference docs are fine. It's so infuriating coming across a project that only has one kind and not the other.
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.
I think conceptually diataxis is brilliant. However, it is not trivial to implement. Every project needs a varying ratio of each component and stacking all forms in a single website in the same format is very ineffective. The ratio also evolves with community adoption and expertise level.
I really wish it was simply more actionable. Documentation is a hard problem, maybe we will figure out a better way one day. Until then docs will only be as good as the amount of time and expertise spent on them, which is usually not as high as it should be due to resource constraints.
> Every project needs a varying ratio of each component and stacking all forms in a single website in the same format is very ineffective
I think Diátaxis _is_ mostly a conceptual framework. It helps me tremendously, totally implementation agnostic. From the site itself:
> Diátaxis strongly prescribes a structure, but whatever the state of your existing documentation - even if it’s a complete mess by any standards - it’s always possible to improve it, iteratively.
This really should be at the top. It was almost frustrating seeing how much other discussion there was here before finally finding mention of Diátaxis.
Examples are crucial to documentation, but they aren't — at least in this view — a kind of documentation, so much as a technique for documenting.
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.
Say what you will about Perl, Perl docs are some of the most helpful. It's standard for docs to have a SYNOPSIS section up front that provides examples of common usage. This is followed by discussion, reference, and often more examples.
I did a bunch of perl in the early-00s, then never touched it again until a random engagement in 2014. It came back IMMEDIATELY. Felt like having conversations with an old friend.
I don't know what it is, its definitely not mathematical purity or consistency, but there's something there witb Larry Wall's linguistics background and general attitude that just stays with you.
The examples in the Perl documentation are very well chosen, too. They aren't just a quick way to get up to speed. They aren't just code that you could use as a starting point and modify for your purposes.
Instead, many of them are almost like exercises to help you work through the ideas that the documentation is presenting. Some of them help you see how a syntax or other language rule applies. Sometimes the documentation presents two pieces of example code and walks you through why they're equivalent, helping you understand the language better. Or why they're almost equivalent and what the differences are.
In a lot of documentation, examples give you a superficial understanding but are a dead end if you want to go beyond superficial. In the Perl documentation, examples are often a bridge to a deeper understanding.
This sort of thing really bugs me when I work with Unity and Unreal. Sometime the documentation for something is just so useless. A lot of the time when trying to understand Unreal nodes, the documentation page is just a picture of the node and the name of the node restated in slightly longer words, as if that helps anything. And so many times when I'm using Unity at £JOB, I just want to know how to use a function properly, and a short example would help so much. It's generally good but some pages just have nothing of value on them. If I could submit my own additions to the Unity docs pages, I would probably end up doing that
Unreal's lack of documentation is hugely frustrating and a massive time sink for me. They very much subscribe to a 'code is documentation' approach (I don't agree), but the 'screenshot of a node' documentation for blueprint is truly beyond parody.
I also had some issues recently where I was trying to build something in the latest Unreal version, and the docs for the thing I was trying to do said they were for that version, but obviously had screenshots from the last major version, which had a completely different interface style and menu items in different places, and as such was almost completely useless. Someone forgot to check it before bumping the version number on the docs
I actually don't know, I just assume the majority of people are americans and that's why they use $. I don't use $ in programming except for string interpolation, so it's never really registered as a variable sigil to me
Every time I use $word in a comment is to be reminiscent of POSIX-style string interpolation for some word. The vast majority of cases where I've seen it are such, only if "word" is numeric do I expect $ is used as a currency symbol.
Radical 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.
No. Examples are there to show how to use this method, and other methods in conjunction.
You can intuit all you want from a method signature, and then you will fail to produce working code because you missed a config, or a preparation step, or don't understand how to process the results, or...
> because you missed a config, or a preparation step
If the specific values of parameters of your mutable state are material to the outcome, then the example is incomplete if they are not specified. Similarly, you wouldn't use `fib(x) = 3` as an example without specifying `x = 4` in your context.
> don't understand how to process the results
Not sure when this would be the case. Do you have an example in mind?
> "it's enough to deduce parameters from method signature"
You don't quote me well. Here's what I actually wrote:
"If the technical spec of a method cannot be intuited from the signature and a handful of canonical examples of usage, then..."
> <the only step usually shown in examples here>
Then those are poor examples. I'm not defending that poor examples beat out good technical specs, or even that bad examples beat out bad technical specs. Merely that, if a user-facing function is not misplaced at the architectural level, then good examples often make good technical specs redundant (for users) and provide strictly greater value (for users).
I'm aware of real world practices. I'm a real world programmer working with real world functional codebases, where parameters material to computations are always exposed explicitly, or at least their monadic context is. It is no pipe dream to highlight these parameters in full examples.
What often is a pipe dream is attempting to formalize and then update English language technical documentation. Ironically, one of the biggest offenders I might point to is the Rocq proof assistant. Their documentation has decent example coverage, but where it doesn't have coverage, and instead only has authoritative-sounding technical specs, it is abysmal. I have gone down rabbit holes to find out the real-world implications of typeclass resolution flags like this one (https://rocq-prover.org/doc/V8.19.0/refman/addendum/type-cla...), for example, only to find out that its behavior has changed from version to version without any update to its technical spec. This is because the spec, being mere English, was not specific enough to even distinguish between these different behaviors.
Why rely on someone to intuit what you could just simply state explicitly? That sounds like you're just asking for trouble if someone doesn't think/intuit in exactly the same way that you do.
We advise developers to include examples in their documentation, often under their own ## Examples heading. To ensure examples do not get out of date, Elixir's test framework (ExUnit) provides a feature called doctests that allows developers to test the examples in their documentation.
Doctests work by parsing out code samples starting with iex> from the documentation. You can read more about them at ExUnit.DocTest.
Personally I am much more tired of lengthy troves of API docs that, while fully specifying the system, do nothing to specify how one is actually supposed to use it in practice, such as the general flow of the program itself, which functions are relevant to what overall operations, in what order certain functions should be called relative to others, how one should handle errors, etc.
If I at least have some examples to get me started, then I can go digging through other documentation (or even just the code) to figure how to do more advanced things... but being unable to even get started is a much bigger frustration IMO.
One time my company paid $5k for a commercial x264 license, and when we asked for some documentation on how to get started with encoding some video frames using their C API, they simply responded "the code is the documentation." With no real examples to go on (at the time in the 2000s there actually wasn't much available online at all), this set me back a good two weeks that I felt was completely unnecessary and completely turned me off to interacting with them at all for the future.
We ended up switching to a hardware solution that was much easier, faster, well-documented, and way friendlier people to talk to.
Given the choice between massive, "complete" documentation with no examples and decent but incomplete docs with good examples, I’ll pick the second every time.
Why? Because if you don’t explain how to actually use something, all the fine-grained details are pointless.
Classic example: try looking up the Java docs around 2003–2005 to figure out how to display an image in a Swing application. Endless pages about Graphics2D and Image and double buffering and what not but not a single mention of the real solution:
FWIW that stuff was put in the Java tutorial (not sure if this is still the case today). The "Visual Index to the Swing Components"[0] (a copy i found online from ~2003) shows JLabel with an image and the docs even begin with "With the JLabel class, you can display unselectable text and images.".
Also : avoid using IT terms in examples (or "self-reference"), it can be confusing. In examples choose a very different field : animals, cars or anything, so that there is a very clear difference between language keywords (what needs to be learned) and the dummy data treated (what can be forgotten after reading).
Here we are trying to explain templates and slots, with "slot" as an html attribute and the dummy data is... "slot". This kind of confusion is useless and makes it more difficult. Almost as if the goal was to be difficult.
I use ImageMagick a lot and kept finding myself Googling for examples. I started writing notes for myself and recently combined them into a small field guide of command-line examples.
I go on to explain each of the arguments, however, which this blog post doesn't necessarily suggest. I think we need both examples and explanations.
My draft is still early, but it’s already useful for everyday tasks like resizing, optimizing, and layering.
Obviously you want detailed documentation too, and examples are great for quickly grasping bigger concepts and how to integrate into other systems. In my experience the best solution are both, where examples all have hyperlinks to the actual documentation for everything involved in the example. React is a good example in my opinion; there is detailed documentation of the api, overviews of the concepts, as well as examples that are included where necessary and as part of a walkthrough.
Even better are the challenges at the end of their examples which force you to rethink what you just read.
I often need both. When I pull up a man page for a tool I haven't used before, I go to straight the bottom to look for an example that matches my use case. Once I have it, I lookup the the specific flags and what they do. Examples aren't meant to be exhaustive, but they certainly help onboard new people faster.
As someone that reads official documentation instead of stackoverflow threads, I support this motion.
There's a couple other maladies that make for unreadable docs. Another is documenting only the last layer added by the Open Source collaborator and not documenting anything below, for example if I'm making an HTTP client:
http.get() makes an HTTP get request
http.set_tcp_params(param=value) sets the TCP parameter param to value
When you could do:
http.get() makes an http get request, which should be a read only requaest, that doesn't affect state of the server. Parameters are typically passed in the URL with ?param=value¶m2=value2 syntax as defined in RFCxxx
http.set_tcp_params() sets parameters of the tcp layer, as defined in RFCxxx, these can include most importantly the MTU which is the max packet size, which might be useful for fitting webpages... (<-- actually the reason the function was implemented at all, but then it was generalized just as an added bonus)
One way to fail in this regard is to use one of those autodocs things, you just lost the battle.
I'd say worked examples and comprehensive references are mutually reinforcing kinds of documentation, meaning you want both. I know I've gotten big mad at JavaScript library/framework documentation that had a few examples but when I actually wanted to learn the API in full, a reference was sorely missing. It was all cutesy "all you have to do is call wango.mumble() with your endpoints and pass the returned object into garthok.narfle() and it will autowire calls from the front end to back-end routes and you can use the time you saved to play with your doggo! :3" tutorial-y stuff. Good for standing up a simple app, but when I had to characterize the framework's behavior somehow I was staring at the source.
PLEASE provide examples and PLEASE provide documentation of every API call's inputs, outputs, and effects.
In my opinion, examples are very helpful, but are not the best documentation; real documentation is better. (It is good to have documentation with examples, and/or to have documentation and also separate examples. Having the source code of the program can also sometimes help with some things that the neither the documentation nor the examples makes clear.)
I try to write good documentation for my programs, although it helps if other people (who do not already know the working of the program) will review it in order to suggest improvements.
This holds true for product documentation as well. Too often docs are just a litany of detailed feature descriptions, which field and button does what, etc.
Feature-list type documentation is orders of magnitude less useful than workflow-type documentation. Majority of the time users are concerned with accomplishing tasks, which if the software is well designed, can be grouped, composed, and illustrated with examples. Key examples can be chosen to both showcase features and illustrate the main paths from "raw materials" to "finished workpiece", at various scopes.
This gap is too often filled by random youtube tutorials of varying quality. It's really telling of the massive blind spot afflicting the makers; they're too close to the details of what they build to see the whole, especially from the perspective of a user.
Yes, for api/token interactions I love examples that show how to generate a token with only permissions for what you are doing. Then pulling said data from API and interacting with it. At least that's how the users that use the product I work on. Security, workflow, and cleanup are great examples.
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 examples that don't even compile right? But on more than one occasions I've used a Microsoft C# library that comes with examples clearly hand made by their engineers (yes I'm that old that it couldn't be LLM output) without checking they work. Somebody has sketched out what ought to work, they haven't tested it, and a reviewer has seen that it looks right and OK'd it, but again, never tested that it works. This is extremely frustrating because the documentation is wrong but now what?
Ah, I do actually have some "real" unit tests where what I'm testing is not directly exposed to users. So e.g. code to correctly find how many bits of precision I need to calculate the decimal output in realistic::Real is tested but users can't ask that so there's no value in documenting it.
Documentation comes in two halves, the examples and the reference, the examples are nice to understand how everything ties together, the reference explain how things work. If I only had one I would pick the reference. But having said that there have been times I would have killed for a simple example.
When I am learning something, I do tend to start with the examples, it is the best way to quickly get a feel for the shape of the domain and it's usage. But then end up in the reference in order to understand and apply what I just learned.
If you are deeply knowledgeable about some library or language, examples become less valuable and the straight forward API documentation becomes essential.
For me examples are "shortcuts for the standard usecases". I use them do I don't have to understand the intricacies of the library.
If I need more, i'll read the full doc. If I'm not in a standard usecase, I will read the full doc
probably one of the best uses of LLMs I've found in recent years. Needed to start integrating rabbitMQ into our application in order in integrate an external service. I had never worked with rabbitmq and while the docs for elixir's rabbitmq library were very good, it left me with a lot of open questions. I hopped on chatgpt and told it what my requirements were and it spat out with a boilerplate. for every scenario, I was able to have an example implementation generated. It still took an additional week of tweaking and changing things but This would have easily taken a month of exploratory programming pre chatgpt. Instead, we had a working proof of concept in a day and a half and had a final version deployed to prod in a month.
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.
for years, i've been secretly wishing that doctests would take off because it seems to really solve two problems at once:
- it puts a simple usage example into the documentation
- you get an easy-to-write, quick-to-run little assertion test that ensures basic functionality is saved
The user model an API exposes and the internal model to implement this can be very different. It's like trying to conclude from the transformation a clockwork does, what it's purpose is (keeping track of time passing). The user model never needs to occur explicitly in the code.
In terms of actually documenting something, examples are not documentation at all -- they are merely illustration. The annotations accompanying the examples (if any) are better documentation than the examples themselves.
Documentation 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.
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.
examples often show the "spirit" of the invention it's intended usage if you like, which explains more what it does than name alone... also reason why I prefer wordy development notes than just a list of parameters it's useful for me to know whether it's what I want quicker than what I think I want based on name
Bullshit.
Examples are the best excuse to not write documentation.
I should be able to come up with an example by looking at the docs, not the other way around.
I just LOVE IT when i read a device datasheet, perform the steps and things don't work. Then i have to download a couple of GB or so of framework and configurator to generate a project that shows me all the details they forgot to put in the datasheet: order of operations, missing requirements, all that stuff.
Even better when the examples are not updated when the device / libraries / framework are updated
No. Please for the love of Cthulhu. I need documentation. Not examples. They will help with the common cases, but common cases are easy, it's corner cases I'm after. Not type signatures - type systems are that would be sufficiently expressive would be badly unsound and undecidable. I need to know assumption the code takes. Specially so with statefull/object-oriented code, aka "why I hate the builder pattern". Too much unsaid assumptions about the order of methods application.
Of course both is best. But let's get real, once part one is there that's all you will get from the first-party. "Docs? Yes, here is our examples." Than for examples you can at least ask someone else if the lib is sufficiently popular. For the prose - gotta reverse-engineer it yourself.
Like a lot of advice for documentation, it's not completely accurate. Good documentation should cover 3 "kinds" of users.
* Absolute beginners/newbies: These users are best helped by showing a "happy path" through the tools, with plenty of examples to show you why things are that way, so they build up an understanding of how things are supposed to work.
* Regular users: These are best helped by a "topic" oriented style of documentation. Topics can take one element of a tool and go really in-depth on it. For example, a HTTP request library might have a topic page entirely dedicated to session authentication, explaining how to persist headers and cookies between requests in the library and what a session object does.
* Power-users/developers: These users are served by reference docs the most. Just a big index of classes, functions and argument doc strings that refer to each other is enough here, because anyone reaching for reference docs is usually doing it because they have a very specific issue.
As for real world examples I'm familiar with; NodeJS libraries often only have beginner docs, and the moment you go off of that happy path it becomes very difficult to reason about what you're doing (not helped by a lot of frameworks preferring you use CLI tools to build up your code, maybe this has changed), the python ecosystem often has good topical docs at the cost of poor reference documentation and C libraries very often only ship with reference documentation.
Programming-wise, it's easy to make reference docs (since they can be derived from comments in the source code) and beginner docs (because you probably have a mental model on how someone is meant to start using something), while writing good topical documentation is an entire skill on its own (since it requires understanding where someone might struggle with something.)
The best documented tools usually have all three covered at the same time, while poorly documented tools usually only have beginner or reference documentation. Only having beginner docs makes it impossible for someone to really learn a tool ("draw the rest of the fucking owl"). Only having topical docs makes it hard to figure out where to start. Only having reference docs is hard to reason about because there's nothing explaining to you how the references are meant to fit together.
Examples are indeed crucial, but conceptual documentation and contract documentation that describes behaviors that cannot be formally made transparent in the language are equally important, and often missing too. In fact, I'd argue they are more important because an example can be easily misunderstood without this surrounding context.
The form the documentation takes depends on the audience.
If the audience is teammates, the _code_ itself is usually the best documentation.
Tests lie about edge cases. A test _might_ be demonstrating an edge case, or the suite might ignore large sections of edge cases.
Documentation is worse, it rarely documents edge cases. Country Y passes legislation and you need to implement it? Yeah, the docs aren't getting updated.
If your audience is a different team, API references (the headers/RPC message schema/javadoc/etc.) are better than written docs. Again, they are less likely to mislead you and are much more likely to work.
Unless, of course, the interfaces are telling fibs about what is allowed. Interfaces that are big buckets of parameters can do that.
Only if your audience is an external organization would documentation be a good primary reference. It meets them where they are, selling them on the capabilities of the software and bootstrapping them to the code.
Please 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 need to fix a problem or actually learn the library.
Also having examples is fine, but they should be considered a bonus; not documentation.
Both are needed for good documentation. You start with the details and then finish with a few examples so that someone who has read the details can check their understanding. Sometimes the example is all you need, but most often there are far more possible combinations of options such that an example of all the useful ones would be several books long (there is no good way to sort/index them so someone wouldn't find the example they need if you wrote them all). So you start with an explanation of each option, and then a few examples that are as different as you can make them so readers get a sense of what is possible and can look back to the explanation to figure out the changes they need to get the example to do what they need.
Good documentation is hard, and very rare these days.
Documentation is like the system it supports too: the only unchanging ones are those nobody is using! I think this is obvious when we compare quality between the historically much slow manual releases with the cadence today, and the documentation of relatively slowly changing projects with newer, faster ones. It's a lot of work to create good documentation; it's even more work to keep it good.
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 manually writing the same thing type tooling is going to give your users anyway.
When I hit docs - I'm much less interested in the specific arguments, and I'm very interested in "Capabilities": Problems this tool can solve.
Examples are a great showcase for that. Especially if I have a specific problem in mind and I just want to know if a "tool" can solve that problem, and how to use it to do so.
---
If I have a type system: I want examples first.
If I don't have a type system: 1) I'm not happy. 2) I want examples first, followed by the detailed arguments/return/data structure docs you're referring to.
> what you're asking for is type definitions
It's the API specification. It's not just the functions and their parameters, it's also an explanation of what they do.
> I'm much less interested in the specific arguments, and I'm very interested in "Capabilities"
And that's exactly what an API specification provides you, and that examples do not. Examples only tell you how to use the API on the same way that the author is using it.
I really want both. I can follow examples and read specifications, but i likely want the simplest example first if I'm using a tool, and then the specifications after i've used it a few times.
it's much harder to imagine everything a tool can do with only the specs, and I'm not clear what things I'm missing. Examples make it concrete
Types don’t explain intent or gotchas. They’re also useful, but you need both.
The most annoying problem I run into with strongly typed languages or even typed python for that matter, is what on earth do I expect this to return?
With python, it could be a mysterious class that isn't explicitly mentioned.
For Rust, you often need to know 4 layers deep of nested types for various error and flow control, and once generics are introduced with the expectation of implemented traits, it all goes out the window.
If I need to declare the type of a value ahead of time, or know it's shape to serialize, check, etc, I want a very clear "this is what it returns, this is how it's expected to be used".
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
I don’t fully agree. Javadoc style documentation should be programmatic and driven by types and inline doc strings. It should just always exist and I would argue having it online is ok but why would not just go to the code itself.
Examples like QuickStart guides should absolutely be required. They serve as the quick entry point and general use of the library. If I only had the code docs I would have no idea how I am supposed to use the api and was my main complaint of many Java libraries historically as they only had a Javadoc.
I think this is almost provably true, for the simple reason that detailed technical documentation can be a substitute for examples, but the reverse isn't true.
1. If you want an example and the docs have an example, great.
2. If you want technical details and the docs have technical details, great.
3. If you want an example but the docs only have technical details, you can still get what you want by spending longer to read and understand the documentation. It's inefficient but it works. Third party examples are also frequently available.
4. If you want technical details but the docs only have examples, you're SOL. You have to hope that the code is available and readable, or just try stuff and hope it works. Third party technical details are rare.
> It's inefficient but it works.
I'm not sure it's inefficient. It gives you the knowledge what is and isn't possible and also the semantics of what you actually do, all things you need to have later anyway. Relying only on examples is a great way to miss unintended side-effects or other consequences.
The first part of that line is "If you want an example...". If you want to learn about more advanced usage of some function, then you don't want an example, and that line doesn't apply to you.
What I say is that you think you want an example, but then either you come back later or you don't and ship slightly broken software.
Did you stop to consider that perhaps other people learn differently than you, and find examples as a way to soften the friction that context switching causes in a job?
I don't understand the resistance to examples being a part of documentation (and not a bonus).
I think you're being unfair. The blog post claimed "Examples are the best documentation". If I use your own logic, shouldn't I say to the blog writer "Haven't you ever thought people learn differently from you?".
I think harimau777 was just expressing his opinion, like the blog owner.
It shouldn't be an either/or situation. Good documentation should include both the API spec _and_ examples. I believe the person you're replying to was complaining about documentation that's _only_ examples since it seems like that's what TFA was advocating for.
sometimes professionals need to fix shit and need exacting clarity
There's a neat mental model that there are four kinds of documentation: tutorials, how-to guides, explanation, and reference.
I think that examples fit into the first or the second kind; I'm not too concerned which category they belong to, because the point is that all kinds all have their place.
Source: https://docs.divio.com/documentation-system/ - someone has already linked it in another comment, but I think it's worth replying because the comments in this thread are arguing about which kind they like the most.
To me, you're describing a specification, a type of documentation, with examples being another type. And I agree that a specification should just list definitions with explanations.
But there's no reason that a document cannot contain both a specification and examples. That's the type I prefer, and that's the type I mostly encounter nowadays. Usually a specification on the left with some examples on the right, maybe even interactive examples.
I think well commented examples are the best documentation but they are absolutely not a substitute for traditional docs.
I used to work on Drupal sites and they have very few examples for how to actually use various functions. So you'd run into instances where you're doing something completely wrong even if the function name makes sense.
The best documentation is type references and examples and a line explaining what the function does. Not one or the other.
https://en.cppreference.com/w/cpp/utility/optional.html Remove the examples and then make sense of _ANY_ of that documentation.
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.
> You optimize for power users not amateurs.
Sure, but you can optimize for one without excluding the other. Adding examples _allows_ amateurs to gain experience and _become_ power user, and imposes near-zero cost on power users who can just skip a couple lines and get into the "real" API doc.
Nobody said don't add examples. Just don't do it before creating proper API docs.
Everyone who disagrees with you are amateurs.
"No true Scotsman would want examples."
I'm far from an amateur and I want to see several concise examples in documentation. That doesn't mean that's all I want to see.
That's not what anyone said. We both said examples are great. They're just not more important than proper API docs.
They're not the best. The best is thorough api docs. The rest is nice to have.
And I'm not no true scotsmaning, I'm just saying most devs are ass. I know, I see people with 20 years of experience on me write buggy trash code that I have to fix. I see people whine about the java docs as if they aren't some of the best damn docs available anywhere. Because they're ass and they can't properly use the tools they're given. They'd rather have examples and copy snippets from SO or have ChatGPT write it for them.
Any professional will appreciate proper documentation. It is literally impossible to create examples for every situation. Api docs, by their nature, cover all use cases because they simply describe what exists not how to use it. So for those of us with the knowledge and intelligence to actually just look at the parts and put them together on our own, ie professionals, API docs are king. Examples are useful sometime, API docs are useful all the time.
But of course if you don't even know the language well enough to read the documentation, you prefer examples.
That's not what anyone said.
That's exactly what you said.
And I'm not no true scotsmaning
You absolutely were. Now you're trying to backpedal.
I think it's a bit harsh to call everyone who disagrees amateur. However, anecdotally it doesn't feel very incorrect. When I do pair programming with less-experienced developers, I'll often watch them glance at the API docs, skim over the technical details, look at the example, copy paste it, and then be confused why it doesn't work. Then I pointedly suggest reading the specific paragraph that explains the confusion they have.
Yeah, I'm not saying it to be mean I'm just calling it as I see it. Can't recall if it was the article or a comment or both, but someone mentioned that it's hard to understand API docs in some cases because it relies on understanding the language itself.
If you don't even know the language well enough to read docs I'd say you're an amateur. And if you're one of those people who just chronically don't read docs you're definitely an amateur. I mean you may have a job and you may even build stuff that kind of works, but unless you're sitting down and looking closely at the details you're not doing things right. You can't be. Doing things right requires looking closely at the details.
And I know from experience that there's a vast number of employed amateurs who write nothing but legacy code.
The annoying part about Python is that searching for the python docs is hard.
E.g. "Python rstrip" (without quotes) in DuckDuckGo does not lead me to the Python docs on page 1.
I've never had that issue with Python.
Now, languages with common / short names? All the time. Go, C, C++, D, etc; even Rust (especially since all the libraries have similarly ambiguous names related to iron oxide).
For C there is excellent documentation and tutorials in man pages and info documents. It's in my experience the best you can find short of reading the code yourself.
In DuckDuckGo you should be using !py rstrip, that's what the bangs are for. But yes, in general most of the good (third-party) python resources have been killed by SEO spam.
help(str.rstrip) in a Python shell? Who needs online docs? In case I want them I also have them offline in Devhelp.
Am I uncommon in that I search for the website/domain I intend to read first and then look for the specific page?
> am I uncommon
I think so!
Examples 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? How do I pass in content-type? Does raise_for_status ignore 204?
Both have their merits, but if developer only has time for one, I'd go for proper doc.
[0] https://requests.readthedocs.io/en/latest/user/quickstart/
It is order of magnitudes easier to understand behavior through examples than through a reference-like documentation. People suck at naming things, and then documenting them. Just today I spent the last few hours trying to figure out how to get something to work because a parameter only worked if another paramter had a specific value. There was too much magic to try and figure out the code, llms wrongfully told me the latest version doesnt support the parameter because it couldn't find any documentation.
Ultimately, creating a small example that I know should've worked and changing things in a way that I could narrow down the problem worked best.
The point to all this is that examples often encapsulate multiple things into a condensed format, that is extremely high fidelity (since it's typically a code example that runs and has output). Things like Api documentation in comparison typically cover a huge surface area, and have way less effort in maintaining them.
Also for the record, I absolutely don't trust libraries on behavior that isn't extremely obvious, explicit and so absolute that it's almost effortless to find out (I am talking first thing on README, entire sections showing that one thing, or definition through types). I just assume that things like behavior around status codes are going to change, and do my best in the calling code to mitigate issues as much as possible.
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 the productivity barrier for one has been broken, the other is a tiny extra effort. In that case, they must provide both, except in the small minority of cases that are exceptionally self-describing, where one (usually docs) is sufficient.
[flagged]
I’m not sure if that’s true.
The number of times I’ve opened FFmpegs man page must number in the hundreds. I think I’m a pretty good conceptually, but I can’t remember all the flags. IE that –s is frame size, while -fs is file size.
And while that man page does have some examples, these days I tend to ask an LLM (or if it’s going to be simple Google) for an example.
That's why the recommended practice with shell usage is to write a script (or alias or function) and to use the long version of the flag in the script. Instead of having a complex invocation of ffmpeg, you'd have `flac2mp3 -q low file`.
Even as an "expert with several decades of experience" there are so many parts to a complex system that I still am a beginner in.
>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.
I agree. Good documentation (nearly) fully specifies program behavior, and doing so with just examples is impractical or impossible.
>occasional users
That's exactly what I'm pointing to in the post:
>When jumping between projects, languages and frameworks, it takes a considerable amount of mental energy to restore the context and understand what is going on.
They're not mutually exclusive you know, you can have both example and a proper technical doc.
Took the words right outta my mouth!
Of course we want a full list of public functions with all the info. But with just a list of functions it's often still not quite clear how you're supposed to setup and call them, unless you dig through the whole list and try to understand how they interact internally. A few short examples on "How do I init the library/framework so I can start using it", "How do I recover from a failure case", etc. makes the docs infinitely more accessible and useful!
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/
Unfair example google has the worst docs in existence. Either a quickstart with one uselessly simplistic example or an autogenerated class list on a totally separate site with no explanations to be found. Often I just end up looking at their libraries source code to learn how to use it.
[dead]
Similarly, 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 haven't had that problem. I just code something up, and poke around to understand some of the terms that it's talking about. Then I start reading about error return codes, why them happen, what kinds of parameters actually mean, etc. No examples are usually needed as long as documentation is complete
The most frustrating things are things that are undocumented at all and only have examples. What the hell kind of shitty documentation is just examples with no idea what parameters could or shouldn't be?!
Sometimes, I just wanna remind myself how to use xargs for some command text replacement in a random one-liner on the terminal.
If I tried to do that with man... I'd have to read (in alphabetical order) the documentation for 6 different command flags. That's how far I'd go to read about the flag -- to actually use it, I'd have to experiment with the command flag until I figured out the actual syntax using my imagination.
Let's say instead that I am in a rush... so I'm skipping that time-consuming process and instead scrolling furhter down for some practical examples... one full page later I find a bunch! ... Except there's only 4 and none of them demonstrate what I need (the syntax is completely different). The docs wasted my time exactly when I most needed it NOT to do that. If I'd instead just googled "xargs replacement example", I would have gotten something I can copy/paste in seconds and could have gotten on with my life!
The moral of the story is this: Don't tell without showing. Don't show without telling. Do both if your goal is to be understood.
Once you have something working the way you like, make your own example and put it on a github repo named "today-i-learned". Then you can refer to it as your own documentation for yourself.
> I'd have to read (in alphabetical order) the documentation for 6 different command flags.
You now you don't need to skim a man page like a physical directory? It's in a computer, just search for the flag you want to use.
I wholeheartedly agree, and would like to remind all man page authors that there’s even a conventional section named EXAMPLE. See man(1) for details. [0]
[0] https://www.man7.org/linux/man-pages/man1/man.1.html#DESCRIP...
Checkout cheat.sh
I have this in a script: `curl cheat.sh/"$1"`
I'm always pleasantly surprised that many man pages do have examples. But, sure, they could be a lot more comprehensive.
I've developed the habit of checking the end of the page, because that's where the examples are, when there are any.
PHP documentation stands out with the comment section, like an integrated stack overflow, with examples and gotchas. It's what made PHP great.
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.
Totally agree but there is tldr for that.
I learned recently that tldr also has separate pages for subcommands.
tldr was created specifically to address this miscoming of the manpages. And it's recent enough to not ship with any distros.
It already exists - tldr. Use it side by side with man.
The state of man pages in the GNU + Linux ecosystem is just atrocious in general. You can thank the GNU Project for that. In sane man pages that actually care about quality, examples are specified where appropriate: https://man.openbsd.org/apropos.1#EXAMPLES
The GNU project choose to separate documentation into reference (man pages) and tutorials and prose (info). It works quite well and in my opinion info is also superior since it is an interactive hypertext system. So you can have cross-references, outlines, alternatives for different audiences, etc. .
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
You 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.
Agreed, examples and reference docs.
When feasible, I'd add repl environments. The ability to quickly modify and test the example can make up for a lot of the shortcomings documentation might have.
I'm honestly surprised there are people who think that only examples are fine. And I'm equally surprised there are people who think only reference docs are fine. It's so infuriating coming across a project that only has one kind and not the other.
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.
[1] https://diataxis.fr/
I think conceptually diataxis is brilliant. However, it is not trivial to implement. Every project needs a varying ratio of each component and stacking all forms in a single website in the same format is very ineffective. The ratio also evolves with community adoption and expertise level. I really wish it was simply more actionable. Documentation is a hard problem, maybe we will figure out a better way one day. Until then docs will only be as good as the amount of time and expertise spent on them, which is usually not as high as it should be due to resource constraints.
I'm not sure what you mean by
> Every project needs a varying ratio of each component and stacking all forms in a single website in the same format is very ineffective
I think Diátaxis _is_ mostly a conceptual framework. It helps me tremendously, totally implementation agnostic. From the site itself:
> Diátaxis strongly prescribes a structure, but whatever the state of your existing documentation - even if it’s a complete mess by any standards - it’s always possible to improve it, iteratively.
This really should be at the top. It was almost frustrating seeing how much other discussion there was here before finally finding mention of Diátaxis.
Examples are crucial to documentation, but they aren't — at least in this view — a kind of documentation, so much as a technique for documenting.
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.
[1]: https://docs.divio.com/documentation-system/
Say what you will about Perl, Perl docs are some of the most helpful. It's standard for docs to have a SYNOPSIS section up front that provides examples of common usage. This is followed by discussion, reference, and often more examples.
For example:
https://perldoc.perl.org/bigrat https://perldoc.perl.org/Archive::Tar
If you're writing docs for your project, consider following the Perl documentation style. Fortunately, that style is itself well documented:
https://perldoc.perl.org/perldocstyle#Description-and-synops...
I did a bunch of perl in the early-00s, then never touched it again until a random engagement in 2014. It came back IMMEDIATELY. Felt like having conversations with an old friend.
I don't know what it is, its definitely not mathematical purity or consistency, but there's something there witb Larry Wall's linguistics background and general attitude that just stays with you.
The examples in the Perl documentation are very well chosen, too. They aren't just a quick way to get up to speed. They aren't just code that you could use as a starting point and modify for your purposes.
Instead, many of them are almost like exercises to help you work through the ideas that the documentation is presenting. Some of them help you see how a syntax or other language rule applies. Sometimes the documentation presents two pieces of example code and walks you through why they're equivalent, helping you understand the language better. Or why they're almost equivalent and what the differences are.
In a lot of documentation, examples give you a superficial understanding but are a dead end if you want to go beyond superficial. In the Perl documentation, examples are often a bridge to a deeper understanding.
This sort of thing really bugs me when I work with Unity and Unreal. Sometime the documentation for something is just so useless. A lot of the time when trying to understand Unreal nodes, the documentation page is just a picture of the node and the name of the node restated in slightly longer words, as if that helps anything. And so many times when I'm using Unity at £JOB, I just want to know how to use a function properly, and a short example would help so much. It's generally good but some pages just have nothing of value on them. If I could submit my own additions to the Unity docs pages, I would probably end up doing that
Unreal's lack of documentation is hugely frustrating and a massive time sink for me. They very much subscribe to a 'code is documentation' approach (I don't agree), but the 'screenshot of a node' documentation for blueprint is truly beyond parody.
I also had some issues recently where I was trying to build something in the latest Unreal version, and the docs for the thing I was trying to do said they were for that version, but obviously had screenshots from the last major version, which had a completely different interface style and menu items in different places, and as such was almost completely useless. Someone forgot to check it before bumping the version number on the docs
> £JOB
Wait a second, do people use $ for `$job` because it's how they earn money and not, as I've always thought, used it as a variable name?
Stop throwing my entire world view out of order please.
I actually don't know, I just assume the majority of people are americans and that's why they use $. I don't use $ in programming except for string interpolation, so it's never really registered as a variable sigil to me
Every time I use $word in a comment is to be reminiscent of POSIX-style string interpolation for some word. The vast majority of cases where I've seen it are such, only if "word" is numeric do I expect $ is used as a currency symbol.
Oh no my PHPness is showing!
Also, many, many countries use $, like Canada.
If you think it would reflect on you better, think of it as indicating regular POSIX shell use?!
(I'm 99% sure it's intended to be reminiscent of that sort of syntax. Example use: https://news.ycombinator.com/item?id=42761939)
> I don't use $ in programming except for string interpolation
... but the entire point of the "$JOB" etc. slang is that it's a string interpolation...
Not how I use it, string interpolation would be $"{job}"
That depends on the language. In unix shell,
and are identical, though the latter is more flexible (Allowing eg. `echo ${JOB:-unemployment}` or `echo ${JOB}SUCKS`).The $ is for variables. And the upper case make it a BASIC variable, instead of something like Perl or PHP.
Some times people put it in angle brackets <JOB>. I have no idea what system use variables like that.
Templates use this syntax in some languages.
Code examples can be executed as unit tests to prevent documentation regressions / bitrot in ways human language can't
But now with LLMs maybe they could begin to check for instance API documentation.
Radical 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.
No. Examples are there to show how to use this method, and other methods in conjunction.
You can intuit all you want from a method signature, and then you will fail to produce working code because you missed a config, or a preparation step, or don't understand how to process the results, or...
If the type signature isn't enough to fully constrain that, you need to fix your typing.
If you have a `Foo` object, it should always be able to do every possible thing a `Foo` can do.
If you need to do something first, it should be a required argument to whatever lets you construct a `Foo` in the first place.
Please constrain function signatures of these: https://developer.auth0.com/resources/labs/actions/sync-stri... and https://github.com/stripe-samples
I see nothing there that seems fundamentally problematic, but I'm not writing type definitions for someone's entire commercial API.
Callbacks are always Hell of course.
Please tell me how you deduce proper payment and auth flows from a function signature alone.
> because you missed a config, or a preparation step
If the specific values of parameters of your mutable state are material to the outcome, then the example is incomplete if they are not specified. Similarly, you wouldn't use `fib(x) = 3` as an example without specifying `x = 4` in your context.
> don't understand how to process the results
Not sure when this would be the case. Do you have an example in mind?
Real world isn't about calculating a fibonacci sequence.
Real world is usually a combination of
- read data
- trasform data
- obtain auth
- prepare data in proper formats
- <the only step usually shown in examples here>
- get results back. Perhaps an error? A stream? A specific format? Could we do retries?
That's why a full example would look like this: https://developer.auth0.com/resources/labs/actions/sync-stri... or https://github.com/stripe-samples and not a "it's enough to deduce parameters from method signature"
> "it's enough to deduce parameters from method signature"
You don't quote me well. Here's what I actually wrote:
"If the technical spec of a method cannot be intuited from the signature and a handful of canonical examples of usage, then..."
> <the only step usually shown in examples here>
Then those are poor examples. I'm not defending that poor examples beat out good technical specs, or even that bad examples beat out bad technical specs. Merely that, if a user-facing function is not misplaced at the architectural level, then good examples often make good technical specs redundant (for users) and provide strictly greater value (for users).
I'm aware of real world practices. I'm a real world programmer working with real world functional codebases, where parameters material to computations are always exposed explicitly, or at least their monadic context is. It is no pipe dream to highlight these parameters in full examples.
What often is a pipe dream is attempting to formalize and then update English language technical documentation. Ironically, one of the biggest offenders I might point to is the Rocq proof assistant. Their documentation has decent example coverage, but where it doesn't have coverage, and instead only has authoritative-sounding technical specs, it is abysmal. I have gone down rabbit holes to find out the real-world implications of typeclass resolution flags like this one (https://rocq-prover.org/doc/V8.19.0/refman/addendum/type-cla...), for example, only to find out that its behavior has changed from version to version without any update to its technical spec. This is because the spec, being mere English, was not specific enough to even distinguish between these different behaviors.
Fair enough :) I fully agree with your response
Cheers mate! Thank you for engaging with my radicalism :)
Why rely on someone to intuit what you could just simply state explicitly? That sounds like you're just asking for trouble if someone doesn't think/intuit in exactly the same way that you do.
Including the technical spec explicitly is still a good idea. Examples without a word of summary would just be strange!
It's merely that I think unstructured English is not a good language for communicating knowledge of how to use an API.
Elixir world makes this easy:
We advise developers to include examples in their documentation, often under their own ## Examples heading. To ensure examples do not get out of date, Elixir's test framework (ExUnit) provides a feature called doctests that allows developers to test the examples in their documentation.
Doctests work by parsing out code samples starting with iex> from the documentation. You can read more about them at ExUnit.DocTest.
They are not the “best.” They are helpful.
I am tired of rudimentary docs that only have examples.
Personally I am much more tired of lengthy troves of API docs that, while fully specifying the system, do nothing to specify how one is actually supposed to use it in practice, such as the general flow of the program itself, which functions are relevant to what overall operations, in what order certain functions should be called relative to others, how one should handle errors, etc.
If I at least have some examples to get me started, then I can go digging through other documentation (or even just the code) to figure how to do more advanced things... but being unable to even get started is a much bigger frustration IMO.
One time my company paid $5k for a commercial x264 license, and when we asked for some documentation on how to get started with encoding some video frames using their C API, they simply responded "the code is the documentation." With no real examples to go on (at the time in the 2000s there actually wasn't much available online at all), this set me back a good two weeks that I felt was completely unnecessary and completely turned me off to interacting with them at all for the future.
We ended up switching to a hardware solution that was much easier, faster, well-documented, and way friendlier people to talk to.
I agree that code is not documentation.
I agree that automatically generated API docs from code is nearly useless.
I agree that examples are important and useful.
But examples are not "the best documentation." Or I should say hyperbole is poor documentation of one's point of view.
Are you saying everyone else's opinion of "best" is wrong other than yours?
Given the choice between massive, "complete" documentation with no examples and decent but incomplete docs with good examples, I’ll pick the second every time.
Why? Because if you don’t explain how to actually use something, all the fine-grained details are pointless.
Classic example: try looking up the Java docs around 2003–2005 to figure out how to display an image in a Swing application. Endless pages about Graphics2D and Image and double buffering and what not but not a single mention of the real solution:
Just put it in a JLabel.
FWIW that stuff was put in the Java tutorial (not sure if this is still the case today). The "Visual Index to the Swing Components"[0] (a copy i found online from ~2003) shows JLabel with an image and the docs even begin with "With the JLabel class, you can display unselectable text and images.".
[0] https://fizyka.umk.pl/~jacek/docs/javatutorial/uiswing/compo...
Also : avoid using IT terms in examples (or "self-reference"), it can be confusing. In examples choose a very different field : animals, cars or anything, so that there is a very clear difference between language keywords (what needs to be learned) and the dummy data treated (what can be forgotten after reading).
An example not to follow : https://developer.mozilla.org/en-US/docs/Web/API/Web_compone...
Here we are trying to explain templates and slots, with "slot" as an html attribute and the dummy data is... "slot". This kind of confusion is useless and makes it more difficult. Almost as if the goal was to be difficult.
I use ImageMagick a lot and kept finding myself Googling for examples. I started writing notes for myself and recently combined them into a small field guide of command-line examples.
I go on to explain each of the arguments, however, which this blog post doesn't necessarily suggest. I think we need both examples and explanations.
My draft is still early, but it’s already useful for everyday tasks like resizing, optimizing, and layering.
https://news.ycombinator.com/item?id=45538609
Obviously you want detailed documentation too, and examples are great for quickly grasping bigger concepts and how to integrate into other systems. In my experience the best solution are both, where examples all have hyperlinks to the actual documentation for everything involved in the example. React is a good example in my opinion; there is detailed documentation of the api, overviews of the concepts, as well as examples that are included where necessary and as part of a walkthrough.
Even better are the challenges at the end of their examples which force you to rethink what you just read.
It's a false dichotomy good documentation should have both - comprehensive reference and examples.
I often need both. When I pull up a man page for a tool I haven't used before, I go to straight the bottom to look for an example that matches my use case. Once I have it, I lookup the the specific flags and what they do. Examples aren't meant to be exhaustive, but they certainly help onboard new people faster.
As someone that reads official documentation instead of stackoverflow threads, I support this motion.
There's a couple other maladies that make for unreadable docs. Another is documenting only the last layer added by the Open Source collaborator and not documenting anything below, for example if I'm making an HTTP client:
http.get() makes an HTTP get request
http.set_tcp_params(param=value) sets the TCP parameter param to value
When you could do:
http.get() makes an http get request, which should be a read only requaest, that doesn't affect state of the server. Parameters are typically passed in the URL with ?param=value¶m2=value2 syntax as defined in RFCxxx
http.set_tcp_params() sets parameters of the tcp layer, as defined in RFCxxx, these can include most importantly the MTU which is the max packet size, which might be useful for fitting webpages... (<-- actually the reason the function was implemented at all, but then it was generalized just as an added bonus)
One way to fail in this regard is to use one of those autodocs things, you just lost the battle.
I'd say worked examples and comprehensive references are mutually reinforcing kinds of documentation, meaning you want both. I know I've gotten big mad at JavaScript library/framework documentation that had a few examples but when I actually wanted to learn the API in full, a reference was sorely missing. It was all cutesy "all you have to do is call wango.mumble() with your endpoints and pass the returned object into garthok.narfle() and it will autowire calls from the front end to back-end routes and you can use the time you saved to play with your doggo! :3" tutorial-y stuff. Good for standing up a simple app, but when I had to characterize the framework's behavior somehow I was staring at the source.
PLEASE provide examples and PLEASE provide documentation of every API call's inputs, outputs, and effects.
While there is often a lack of examples in documentation, a lack of cogent conceptual explanations is unfortunately even more widespread.
In my opinion, examples are very helpful, but are not the best documentation; real documentation is better. (It is good to have documentation with examples, and/or to have documentation and also separate examples. Having the source code of the program can also sometimes help with some things that the neither the documentation nor the examples makes clear.)
I try to write good documentation for my programs, although it helps if other people (who do not already know the working of the program) will review it in order to suggest improvements.
This holds true for product documentation as well. Too often docs are just a litany of detailed feature descriptions, which field and button does what, etc.
Feature-list type documentation is orders of magnitude less useful than workflow-type documentation. Majority of the time users are concerned with accomplishing tasks, which if the software is well designed, can be grouped, composed, and illustrated with examples. Key examples can be chosen to both showcase features and illustrate the main paths from "raw materials" to "finished workpiece", at various scopes.
This gap is too often filled by random youtube tutorials of varying quality. It's really telling of the massive blind spot afflicting the makers; they're too close to the details of what they build to see the whole, especially from the perspective of a user.
> than workflow-type documentation.
Yes, for api/token interactions I love examples that show how to generate a token with only permissions for what you are doing. Then pulling said data from API and interacting with it. At least that's how the users that use the product I work on. Security, workflow, and cleanup are great examples.
Even 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 examples that don't even compile right? But on more than one occasions I've used a Microsoft C# library that comes with examples clearly hand made by their engineers (yes I'm that old that it couldn't be LLM output) without checking they work. Somebody has sketched out what ought to work, they haven't tested it, and a reviewer has seen that it looks right and OK'd it, but again, never tested that it works. This is extremely frustrating because the documentation is wrong but now what?
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.
Ah, I do actually have some "real" unit tests where what I'm testing is not directly exposed to users. So e.g. code to correctly find how many bits of precision I need to calculate the decimal output in realistic::Real is tested but users can't ask that so there's no value in documenting it.
The dlang website generator does not succeed unless all the coding examples run successfully.
i have at times looked at tests to get an idea of how the developer expected the code to be used.
Examples are the best `quick start` documentation. Comprehensive manuals/references are the best documemtation.
> One popular community-based project in the Clojure world is clojuredocs.org, a site where people contribute examples for built in functions
When I was learning php in school, the examples / discussions on every documentation page were always the most helpful bit.
Documentation comes in two halves, the examples and the reference, the examples are nice to understand how everything ties together, the reference explain how things work. If I only had one I would pick the reference. But having said that there have been times I would have killed for a simple example.
When I am learning something, I do tend to start with the examples, it is the best way to quickly get a feel for the shape of the domain and it's usage. But then end up in the reference in order to understand and apply what I just learned.
Examples are the best Documentation to learn.
If you are deeply knowledgeable about some library or language, examples become less valuable and the straight forward API documentation becomes essential.
When I was working on Mathematica, a lot of effort was put in to making examples for each doc page. One example (that I didn't work on) picked at random: https://reference.wolfram.com/language/ref/RandomVariate.htm...
The best docs are the ones that satisfy user needs. https://passo.uno/seven-action-model/
For me examples are "shortcuts for the standard usecases". I use them do I don't have to understand the intricacies of the library. If I need more, i'll read the full doc. If I'm not in a standard usecase, I will read the full doc
OCaml is really bad for this. Zero examples in its docs.
The best docs with examples I've seen are Qt (probably the best documentation overall), Rust and Go.
probably one of the best uses of LLMs I've found in recent years. Needed to start integrating rabbitMQ into our application in order in integrate an external service. I had never worked with rabbitmq and while the docs for elixir's rabbitmq library were very good, it left me with a lot of open questions. I hopped on chatgpt and told it what my requirements were and it spat out with a boilerplate. for every scenario, I was able to have an example implementation generated. It still took an additional week of tweaking and changing things but This would have easily taken a month of exploratory programming pre chatgpt. Instead, we had a working proof of concept in a day and a half and had a final version deployed to prod in a month.
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.
That's a big reason that I work hard on test harnesses[0].
[0] https://littlegreenviper.com/testing-harness-vs-unit/#sample
I regularly need reference docs in hour 2 of trying something new as the examples don't cover my use case.
for years, i've been secretly wishing that doctests would take off because it seems to really solve two problems at once:
- it puts a simple usage example into the documentation - you get an easy-to-write, quick-to-run little assertion test that ensures basic functionality is saved
The "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!
The user model an API exposes and the internal model to implement this can be very different. It's like trying to conclude from the transformation a clockwork does, what it's purpose is (keeping track of time passing). The user model never needs to occur explicitly in the code.
I am involved in a project that has little documentation and many examples. It sucks. A good spec or manual is all you need.
It's like googling "how to do XYZ with grep" instead of just typing "man grep" in the terminal.
In terms of actually documenting something, examples are not documentation at all -- they are merely illustration. The annotations accompanying the examples (if any) are better documentation than the examples themselves.
Documentation 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.
php.net was great for this back in the 2000s.
I agree. When we moved to Python, I really missed all the examples that php had that the Python docs didn't.
tldr.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.
I wish it was a linter rule that people can't add type-hints until they've added at least one example.
examples often show the "spirit" of the invention it's intended usage if you like, which explains more what it does than name alone... also reason why I prefer wordy development notes than just a list of parameters it's useful for me to know whether it's what I want quicker than what I think I want based on name
Bullshit. Examples are the best excuse to not write documentation. I should be able to come up with an example by looking at the docs, not the other way around.
I just LOVE IT when i read a device datasheet, perform the steps and things don't work. Then i have to download a couple of GB or so of framework and configurator to generate a project that shows me all the details they forgot to put in the datasheet: order of operations, missing requirements, all that stuff.
Even better when the examples are not updated when the device / libraries / framework are updated
No. Please for the love of Cthulhu. I need documentation. Not examples. They will help with the common cases, but common cases are easy, it's corner cases I'm after. Not type signatures - type systems are that would be sufficiently expressive would be badly unsound and undecidable. I need to know assumption the code takes. Specially so with statefull/object-oriented code, aka "why I hate the builder pattern". Too much unsaid assumptions about the order of methods application.
Why not both? That way you can use the docs if you are learning the language AND if you already know the language but are looking for deep details.
Of course both is best. But let's get real, once part one is there that's all you will get from the first-party. "Docs? Yes, here is our examples." Than for examples you can at least ask someone else if the lib is sufficiently popular. For the prose - gotta reverse-engineer it yourself.
I agree. I don't understand some of the black and white thinking in the comments.
Carefully chosen examples are best documentation. Badly chosen examples are a mediocre documentation.
Like a lot of advice for documentation, it's not completely accurate. Good documentation should cover 3 "kinds" of users.
* Absolute beginners/newbies: These users are best helped by showing a "happy path" through the tools, with plenty of examples to show you why things are that way, so they build up an understanding of how things are supposed to work.
* Regular users: These are best helped by a "topic" oriented style of documentation. Topics can take one element of a tool and go really in-depth on it. For example, a HTTP request library might have a topic page entirely dedicated to session authentication, explaining how to persist headers and cookies between requests in the library and what a session object does.
* Power-users/developers: These users are served by reference docs the most. Just a big index of classes, functions and argument doc strings that refer to each other is enough here, because anyone reaching for reference docs is usually doing it because they have a very specific issue.
As for real world examples I'm familiar with; NodeJS libraries often only have beginner docs, and the moment you go off of that happy path it becomes very difficult to reason about what you're doing (not helped by a lot of frameworks preferring you use CLI tools to build up your code, maybe this has changed), the python ecosystem often has good topical docs at the cost of poor reference documentation and C libraries very often only ship with reference documentation.
Programming-wise, it's easy to make reference docs (since they can be derived from comments in the source code) and beginner docs (because you probably have a mental model on how someone is meant to start using something), while writing good topical documentation is an entire skill on its own (since it requires understanding where someone might struggle with something.)
The best documented tools usually have all three covered at the same time, while poorly documented tools usually only have beginner or reference documentation. Only having beginner docs makes it impossible for someone to really learn a tool ("draw the rest of the fucking owl"). Only having topical docs makes it hard to figure out where to start. Only having reference docs is hard to reason about because there's nothing explaining to you how the references are meant to fit together.
when possible (python, golang and many others) I just go and read the source..
wait, isn't this a just-solved problem by asking your AI?
Only if it's aware of your platform/programming language/etc
Examples are indeed crucial, but conceptual documentation and contract documentation that describes behaviors that cannot be formally made transparent in the language are equally important, and often missing too. In fact, I'd argue they are more important because an example can be easily misunderstood without this surrounding context.
Examples are also terrible as people will confuse them for the subject.
also unit tests
I’d say the part of the unit test that is helpful is the example of using the code.
It has a pro over documented examples in that they are _guaranteed_ to be correct.
[dead]
[dead]
This is why LLMs won.
Useless documentation means half-arsed is better.
The world of IT is broken, what sort of idiot gives Linux to their parents when as a trained developer man is so useless?
It's just excuse after excuse. Unit tests are documentation sort of garbage.
That's what's mind blowing about LLMs, IT devs are so bad LLMs are better. Hacker News comments also confirm this.
The form the documentation takes depends on the audience.
If the audience is teammates, the _code_ itself is usually the best documentation.
Tests lie about edge cases. A test _might_ be demonstrating an edge case, or the suite might ignore large sections of edge cases.
Documentation is worse, it rarely documents edge cases. Country Y passes legislation and you need to implement it? Yeah, the docs aren't getting updated.
If your audience is a different team, API references (the headers/RPC message schema/javadoc/etc.) are better than written docs. Again, they are less likely to mislead you and are much more likely to work.
Unless, of course, the interfaces are telling fibs about what is allowed. Interfaces that are big buckets of parameters can do that.
Only if your audience is an external organization would documentation be a good primary reference. It meets them where they are, selling them on the capabilities of the software and bootstrapping them to the code.
[dead]