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 p

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 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 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.