Perhaps the biggest driver of docs success is prestige. How cool are the docs tools, and how proud are you to have contributed to the docs?
Which tools do this best? Racket docs look pretty great, for example.
Related Posts
I've been writing docs for different programming language operators (+, *, == and so on). Each one gets a separate web page.
I've suddenly realised that / is much harder! docs/+ and docs/== is fine, but docs// just doesn't work as a URL in a static site.
Any ideas?
There are docs resources like https://diataxis.fr/ that categorise documents based on format and intended audience.
They don't say where you should start, or what order you should write docs.
I'm currently thinking README > reference > tutorial > how-tos. Agree/disagree?
Go has an elegant approach to defining example functions, which are shown in docs as `main()` with the output: https://go.dev/blog/examples