Documenting Not Just "How" but "Why"


Being fairly “old school” and largely self-trained, I’m used to writing instructions about how to use a certain feature (Do 1, do 2, do 3, you’re done). Recently, I’ve been challenged to also document why, which I interpret (though I could be missing the point) as the rationale for using a feature or “what this does for you,” rather than “what this does.”

So naturally, I tried “Googling” how to document “why” and surprisingly came up with nothing, or at least nothing I could find in a few seconds of scanning the search results.

I thrive on examples, so if I could see the difference, I’d probably be able to understand it. I’m throwing myself on the mercy of the forum members and asking for samples or ideas about how to document “why”.



This is basically information typing, or information mapping… the difference between a procedure, a concept, and a reference topic. If you look up “concept vs reference vs procedure” you’ll (or information mapping or information typing), you’ll find a wealth of information.

Basically, you really don’t just want to tell someone to do something. This would be akin to my telling you who to vote for. You would want me to tell you why. And that why can include additional information covered in reference (parameters) or overview information (why that candidate is so cool and will rock your world). Or whatever.

Does that make sense?


Actually, that was really helpful. Thanks.


Good one Sue.
I would like to add to it. An example or a use case would help answer the Why for the user.



Something I would suggest is to discuss alternatives or why something isn’t an alternative.

So if this feature is what you’re suggesting but it sounds like another feature, why are you recommending this particular one. Since cases could be that the other feature is deprecated, only works on a single OS, less efficient, etc.