Comment by Vegenoid
2 years ago
I recently created some documentation for a process at work where I explained the 'why' for most of the steps and commands. Not in great detail, but just a bit of detail. I thought that it was good as a step-by-step recipe, while also giving context that could help someone in the event that something didn't go according to plan.
I was asked to remove much of the context that I provided, so as not to confuse the reader, and to make it as direct as possible. This is documentation intended for experienced, technical professionals. I think that the revised documentation is less helpful.
I had the same thing. I took the reader through the journey of "why" they should want to work in this way, but apparently that's confusing.
That actually the important part though. If people don't know why they are doing something, they don't do it.
Perhaps you could compromise by moving the “whys” into an appendix to the guide with references from the “how” section.
Perhaps it could be restructured to separate out the howto from the explanation to serve the reader’s intended use at the time as described here: https://diataxis.fr
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/