3 ms·
I still wish manuals are written in the old way, like this one: https://archive.org/details/gwbasicusersmanual_202003 https://archive.org/details/gwbasicusersma
by ferguess_k 8mo ago
I still wish manuals are written in the old way, like this one: https://archive.org/details/gwbasicusersmanual_202003 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/ https://go.dev/doc/
- WillAdams 8mo agoWhat is the new way in which manuals should be written? I've been trying via Literate Programming: http://literateprogramming.com/ http://literateprogramming.com/ and applying the concepts of: https://diataxis.fr/ https://diataxis.fr/ (originally developed at: https://docs.divio.com/documentation-system/ 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/gcodepreview.pdf https://github.com/WillAdams/gcodepreview/blob/main/gcodepre...
- ferguess_k 8mo agoYeah 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.