Documentation is a pet topic of mine. In my experience poor documentation is not so much a technical problem as it is a cultural one. Improving the technological side is good, but people who want to write quality documentation will always find a way, even if it is a plain text file check into the repo.
What do I mean by cultural problem? Culture is mostly descriptive rather than prescriptive, which means that "culture" is they way people act, not the way they ought to act. If there is poor documentation culture we cannot just wag our finger and say "you need to document this". The Neovim ecosystem is a great example: we have all the tools we need to ship documentation with plugins and that documentation is available from within the text editor, yet so many plugin authors don't use it and instead just do a braindump into the README. Why? I don't know, but that is the way it is. So instead of typing `:help topic` I have to navigate to the repo and dig through the README file. I don't know where this aversion to writing documentation comes from. But from my anecdotal observations it looks like programmers and computer scientists seem to have a general problem of putting themselves into someone else's shoes. In my opinion the [Diataxis](https://diataxis.fr/) framework is a very good way of structuring documentation. There are four types of documentation: * Tutorials help overcome the "OK, what do I do now?" problem. When I download some program or library I have no idea how to use it. A tutorial takes the user by the hand and gives a taste of what the technology is like without going into much detail * How to guides are concrete problem-solution recipes * Everyone knows what a reference is, so moving on * Explanation is prose that explains in detail how things fit together, but not in such minute detail as the reference. A textbook like K&R C is explanation. I think the Nim documentation has the reference part covered well, but the other parts are lacking. The explanation part is the weakest. Mastering Nim is a pure reference book with some opinionated boxes sprinkled in. The closest we have is Nim in Action, but that book predates even version 1.0 of Nim.
