4 ms·
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 consciousl
by 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 agoThat'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 agoOh 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 agoA 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.