I've realised that the expression problem applies to docs just as much as code.
E.g. for a PL, do you organise syntax highlighting docs with all editors together, or do you have a separate page for all relevant plugins of a single editor?
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?
I've been playing with labels on my code blocks. Sometimes I have useful labels, other times it's just "Example 2".
It's also unclear exactly where I put the label: Inside the box? Outside?
Are there any docs sites that do this really well?