Comment by ferguess_k
17 days ago
I still wish manuals are written in the old way, like this one: https://archive.org/details/gwbasicusersmanual_202003
It is not only a dump of functions, but also with examples for each one of them. I think the Go one is pretty good: https://go.dev/doc/
What is the new way in which manuals should be written?
I've been trying via Literate Programming:
http://literateprogramming.com/
and applying the concepts of:
https://diataxis.fr/
(originally developed at: https://docs.divio.com/documentation-system/) which divides documentation along two axes:
- Action (Practical) vs. Cognition (Theoretical)
- Acquisition (Studying) vs. Application (Working)
resulting in a matrix of four things
- Tutorials
- How-to Guides
- Explanation (of the code)
- Reference (of the code)
which seems to be working well for my current project: https://github.com/WillAdams/gcodepreview/blob/main/gcodepre...
Yeah I think that's pretty good. I'd say Reference + Explanation + Examples is good enough, like the GWBASIC example -- it doesn't give tutorial-size code, just snippets for each function. But having a tutorial section is definitely more helpful.