3 ms·

Please do not make me click on "reference" to get to "API docs". I love diataxis, but dear lord, do not make me click an extra time to get to the thing I actual

by rjmill 2mo ago

Please do not make me click on "reference" to get to "API docs". I love diataxis, but dear lord, do not make me click an extra time to get to the thing I actually need 95% of the time. Overall, the movement is good, except for how it tends to turn 1-click docs into 2-click docs (or more for folks who don't know that API docs probably live under reference.) You are allowed to have a top level tab/link to API docs. Please do not hide those from me while you "improve" your docs.

vanderZwan 2mo ago
I'm genuinely confused about what one would expect under "reference" that isn't effectively API-shaped (in the context of software). Like, I've never consciously thought of this before but I can't remember a time that they haven't effectively been synonyms in my mind when I'm navigatig documentation.
- rjmill 2mo ago
  That's part of the problem. Some projects, when they move to diataxis, will create a top level section called "reference" and have a single item under it called "API" (or similar.) Depending on the docs theme, it can require clicking through to get to it. It is a minor annoyance. edit: Also gonna tack onto this that my original comment reads way more acerbic than I actually feel. I was sleepy and didn't proofread for tone like I normally do.
  - vanderZwan 2mo ago
    Oh like that. I was thinking of situations where "reference" just directly links to the API keyword index, e.g. the P5 docs[0], putting a redundant extra page between that would annoy me too. [0] https://processing.org/reference https://processing.org/reference
- rlpb 2mo ago
  A lookup table of normative specifications for every API call is Reference material. But a tour of API concepts is not (that would be Explanation). Nor is a Tutorial that introduces the API. A lookup table of normative specifications of CLI arguments would also be Reference. So they are not synonymous. To be clear, I'm not advocating for navigation that must always have this structure in cases where it's redundant. I think people should do what makes sense. But I think it is nevertheless useful to not mix the different categories.

by rjmill 2mo ago

vanderZwan 2mo ago

I'm genuinely confused about what one would expect under "reference" that isn't effectively API-shaped (in the context of software). Like, I've never consciously thought of this before but I can't remember a time that they haven't effectively been synonyms in my mind when I'm navigatig documentation.

rjmill 2mo ago
That's part of the problem. Some projects, when they move to diataxis, will create a top level section called "reference" and have a single item under it called "API" (or similar.) Depending on the docs theme, it can require clicking through to get to it. It is a minor annoyance. edit: Also gonna tack onto this that my original comment reads way more acerbic than I actually feel. I was sleepy and didn't proofread for tone like I normally do.
- vanderZwan 2mo ago
  Oh like that. I was thinking of situations where "reference" just directly links to the API keyword index, e.g. the P5 docs[0], putting a redundant extra page between that would annoy me too. [0] https://processing.org/reference https://processing.org/reference
rlpb 2mo ago
A lookup table of normative specifications for every API call is Reference material. But a tour of API concepts is not (that would be Explanation). Nor is a Tutorial that introduces the API. A lookup table of normative specifications of CLI arguments would also be Reference. So they are not synonymous. To be clear, I'm not advocating for navigation that must always have this structure in cases where it's redundant. I think people should do what makes sense. But I think it is nevertheless useful to not mix the different categories.