[ferguess_k]

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/

[WillAdams]

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

[ferguess_k]

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.