Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

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: