💾 Archived View for dioskouroi.xyz › thread › 24939227 captured on 2020-10-31 at 00:51:03. Gemini links have been rewritten to link to archived content
-=-=-=-=-=-=-
________________________________________________________________________________
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 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.
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.
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.
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
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 :)