Hacker News new | past | comments | ask | show | jobs | submit login

As a tech writer I love the concepts of Diataxis but don't agree with it being invoked here. Context is critical in all four of its quadrants, and its model doesn't apply uniformly to every aspect of every application.

GP did IMO the right thing by understanding the audience first in order to judge what level of context is appropriate. That should be rule 0 before anything in Diataxis gets involved.




I think another factor is the medium through which the docs are to be consumed. If the intended audience are "experienced, technical professionals" as the ggp says, but those folks are arriving at the docs primarily from search engines, then it's likely they are in "how-to mode" [0].

People in "how-to mode" are almost always time-constrained. They need immediate answers so interspersing the why with the how would slow such readers down (since they have to scan more text than they need to [1]). Their impatience will often cause them to bounce from your web page back to the search engine in search of other sources that can provide them with immediate answers.

Without additional context on the medium of delivery of the docs (in-app vs web page vs PDF), it's hard for us commenters to say with certainty whether the decision to remove the "why" was a good call or not.

0: https://diataxis.fr/how-to-guides/

1: https://www.nngroup.com/articles/information-foraging/




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: