←back to thread

Examples are the best documentation

(rakhim.exotext.com)
401 points Bogdanp | 2 comments | 09 Oct 25 19:34 UTC | HN request time: 0.432s | source
Show context
smokel ◴[10 Oct 25 05:34 UTC] No.45535616[source]▶
The Diátaxis framework [1] provides a nice suggestion of different types of documentation, and when to use them. None of these types is "best", each serves a different purpose.

[1] https://diataxis.fr/

replies(3): >>45536406 #>>45538965 #>>45539617 #
1. musebox35 ◴[10 Oct 25 08:05 UTC] No.45536406[source]▶
I think conceptually diataxis is brilliant. However, it is not trivial to implement. Every project needs a varying ratio of each component and stacking all forms in a single website in the same format is very ineffective. The ratio also evolves with community adoption and expertise level. I really wish it was simply more actionable. Documentation is a hard problem, maybe we will figure out a better way one day. Until then docs will only be as good as the amount of time and expertise spent on them, which is usually not as high as it should be due to resource constraints.
replies(1): >>45537100 #
2. nevertoolate ◴[10 Oct 25 10:05 UTC] No.45537100[source]▶
I'm not sure what you mean by

> Every project needs a varying ratio of each component and stacking all forms in a single website in the same format is very ineffective

I think Diátaxis _is_ mostly a conceptual framework. It helps me tremendously, totally implementation agnostic. From the site itself:

> Diátaxis strongly prescribes a structure, but whatever the state of your existing documentation - even if it’s a complete mess by any standards - it’s always possible to improve it, iteratively.