Ask HN: Why are documentation only showing 1 example if any
It's now pretty clear that learning is more effective when you have a larger dataset of examples. Why are programing documentations only showing one example per function, if any, instead of dozens?
11 comments
This might add some insight into the problem. https://fromtoschool.com/why-most-programming-tutorials-are-...
Because writing documentation is boring and done by volunteers. Unpaid people tend to do stuff that is interesting for them, not useful for you. Even paid people tend to do the same if not pressed, so what you get is what you pay for.
Depends on the documentation. Here's 20-ish examples for one function: https://relishapp.com/rspec/rspec-mocks/docs/setting-constra...
If you have people and time for docs, you'll have good docs.
If you have people and time for docs, you'll have good docs.
We just have automatic tests that use the thing in every possible way. We have them because that's how we've developed and debugged the function. Best documentation ever.
A comprehensive unit test suite is the best documentation your code can have :)
Only if your testing framework allows those tests to be cleanly expressed and readable. Most of the tests I look at are inscrutable and the majority are for handling corner cases, with maybe a handful for common cases.
The best documentation your code can have is the docs written by paid applications engineers
The best documentation your code can have is the docs written by paid applications engineers
On the opposite, and more irritating side, you have documentation like Ansible's where the core functionality is only explained by examples.
I would've loved to know the exact format of the inventory file specified on a single page, or the list of all supported Jinja methods with a quick description of each, but no, pages and pages of just conversational examples.
Which is great when starting out, and absolutely awful past that, so you is click through maybe relevant pages and Ctrl-F what you're looking for.
I would've loved to know the exact format of the inventory file specified on a single page, or the list of all supported Jinja methods with a quick description of each, but no, pages and pages of just conversational examples.
Which is great when starting out, and absolutely awful past that, so you is click through maybe relevant pages and Ctrl-F what you're looking for.
To add, I like ansibles module documentation. Every option is explained and most times there is more than one example in how to use the modules.
Quality documentation is very difficult to produce and maintain.
On top of adopting a different mindset when writing docs (you'll need to phrase concepts and provide examples to cater for users who probably don't share the same intimate knowledge you have of the codebase), there's a high cost associated with upkeep. Ensuring that your docs always align with the implementation might be straightforward for smaller applications, but as your API surface grows so will the cracks that outdated documentation will slip through.
There are a few examples of tools which are designed to lessen the burden (that I know of):
- To generate usage examples from your code, Go has the idea of testable examples (https://blog.golang.org/examples) which get rendered in the documentation but are declared as normal functions. These can be easily unit tested.
- To provide usage examples in code without resorting to unit tests, Clojure has `comment` forms (https://clojuredocs.org/clojure.core/comment) which are normal expressions but ignored by the compiler. You can define arbitrary expressions within a comment form (e.g. to execute another function), so these can be used to define usage examples and placed next to the functions they call.
On top of adopting a different mindset when writing docs (you'll need to phrase concepts and provide examples to cater for users who probably don't share the same intimate knowledge you have of the codebase), there's a high cost associated with upkeep. Ensuring that your docs always align with the implementation might be straightforward for smaller applications, but as your API surface grows so will the cracks that outdated documentation will slip through.
There are a few examples of tools which are designed to lessen the burden (that I know of):
- To generate usage examples from your code, Go has the idea of testable examples (https://blog.golang.org/examples) which get rendered in the documentation but are declared as normal functions. These can be easily unit tested.
- To provide usage examples in code without resorting to unit tests, Clojure has `comment` forms (https://clojuredocs.org/clojure.core/comment) which are normal expressions but ignored by the compiler. You can define arbitrary expressions within a comment form (e.g. to execute another function), so these can be used to define usage examples and placed next to the functions they call.
Because programming documentation is often written by programmers and not teachers and most programmers doesn't know how to teach. Documentation without any (or few) examples is like math textbooks with only proofs and no exercises.
If it's open source the unit tests are often the best place to start for examples
PHP just let the community write examples in their docs and the results were spectacular. Some years ago they removed that part but had to put it back shortly due to massive requests. Could be one of the key decisions they made at the very beginning that turned their language into one of the most popular ever made
Most documentation is bad and seems to promote formality over usefulness. Examples go a long way.
The most recent example of good docs I have come across recently is svelte.dev
The most recent example of good docs I have come across recently is svelte.dev
In a perfect world most software would have a wiki page that would have dozens of examples showing proper usage. That would certainly help me a lot.