Look at gnucash to see the best example in the world on how to document a program

The documentation of every FOSS tool I encounter leaves something significant to be desired. The state of docs in software (FOSS and non-FOSS both) are mostly a shit-show across the board.

But exceptionally, the gnucash project demonstrates exceptionally good docs. There is a separate package for the docs in Debian (gnucash-docs), which is what the Debian project suggests when the docs are significant in size. The /usr/share/doc/gnucash-docs dir has:

AUTHORS
changelog.Debian.gz
changelog.gz
copyright
gnucash-guide-de/
gnucash-guide-de.pdf.gz
gnucash-guide-en/
gnucash-guide-en.pdf.gz
gnucash-guide-it/
gnucash-guide-it.pdf.gz
gnucash-guide-ja/
gnucash-guide-ja.pdf.gz
gnucash-guide-pt/
gnucash-guide-pt.pdf.gz
gnucash-help-de/
gnucash-help-de.pdf.gz
gnucash-help-en/
gnucash-help-en.pdf.gz
gnucash-help-it/
gnucash-help-it.pdf.gz
gnucash-help-pt/
gnucash-help-pt.pdf.gz
NEWS.gz
README.gz

PDFs are great because web browsers and HTML have become such a shit-show. PDFs nearly guarantee you will see the doc as intended by the creator, without any dependency on a functional cloud with hosts that never change. There is also an HTML version that simply works offline, images and all (unlike ImageMagick, where the offline HTML is totally dysfunctional). The app’s built-in help goes straight to the topic seamlessly. It’s quite thorough documentation. They have 184 figures.

The only thing they seemed to have missed:

$ man gnucash
No manual entry for gnucash

Oops! Can’t get everything right.

One of the shittiest things I’ve seen on a lot of projects are docs that reference Cloudflare sites. 🤦 So you not only need Internet access, but you also need to lick Cloudflare’s boots, dance for the captchas, etc. And the Debian project is okay with that - yikes! I don’t think gnucash does that anywhere.

Anyway, before documenting a FOSS package, please look at gnucash for a good example (but of course there should always be a man page).