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