Why not integrate them with the code à la Literate Programming? http://literateprogramming.com/ http://literateprogramming.com/ The bigger issue is that one r

Why not integrate them with the code à la Literate Programming? http://literateprogramming.com/ http://literateprogramming.com/ The bigger issue is that one really needs multiple types of documentation and they _all_ need to be kept in synch, and that's the real deal-breaker (and working out an easy way to do that would be a game changer). The problem with LP of course is that the typeset source of TeX: The Program is not what most users want, and even a Literate version of Plain TeX (if it existed --- why it does not is a separate discussion) doesn't suit most users who want instead an easy-to-use macro package (hence the popularity of LaTeX) and a template/sample document to start with and _maybe_ a tutorial, and when there is no other recourse, a manual with examples and an index. https://diataxis.fr/ https://diataxis.fr/ put forward two axes: Action/Cognition and Aquisition/Application and that this results in 4 different sorts of documentation which are needed: - Tutorials - How-to Guides - Explanation - Reference which feels like a bit of confusing overlap to me, and I've been trying to simplify it down to: - readme file --- what the project does --- mostly marketing fluff with some pretty images - template file(s) --- a set of examples showing all possible usages of the overall project, _and_ including a valid example of each possible command where it should be possible for a user to select a template matching the specifics of their project and get started It is expected that most users will only avail themselves of those two pieces of documentation - manual which includes a command glossary and an index --- again, the command glossary includes a valid example of usage for each command Which exists mostly for tech support purposes --- when queried on usage the reply is usually, "See sub-section X.Y, paragraph Z on pg. ###" - typeset source code with comments --- which _should_ only need to be seen by developers working on the code