Hacker News Reader

Comment by rjmill | Hacker News Reader

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.

View on HN

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.

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.

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

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.

Reply on news.ycombinator.com