[kjellsbells]

I didn't have defending Word on my todo list today,... but Word would totally be the wrong tool for this,so it isnt fair to compare.

The tragedy is that serious large document authoring systems died with the invention of hypertext and the CDROM. Instead of an elegant set of FrameMaker or Interleaf documents for print you got a cdrom with a private site. And then once the web took off, just a site. Something got lost in that transition beyond the pallet of manuals showing up on your loading dock when you bought a system.

Sadly because Word won, technical authors still try to produce some content with it, but (not their fault) it's a horrible broken experience for both writer and reader. One example is the 3GPP specs that define how the mobile phone network works. Giant 200 page Word docs that take minutes to open and paginate.

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