Comment by rjmill

19 hours 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.

3 comments

rjmill

Reply
vanderZwan  18 hours 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  12 hours 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.