When I look back on our school days, I can’t help but think just how much more we all could have learned and how much better we could have learned it, if our textbooks and instructors had simply stated why the subject content was important. From high school math concepts to abstract computer science theories, we’ve all taken courses that neglected to explain the importance or application of the subject matter. Unfortunately I see the same problem in a lot of technical documentation that I come across. So, in this short article I’ll highlight the importance of adding “why” to your documentation.
Whenever an audience is presented with information, be it a user manual, a presentation slide, comments in code etc., an explanation of why they need to know the information is important. Explaining “why” helps ground the audience in the subject matter and gives the information purpose. Without this, your audience may be lost.
Below are some of the most common factors for why you should explain “why” when presenting information:
First up are design decisions. Design decisions play a critical role in how things turn out the way they do. They are made based on a variety of factors which can include product requirements, historical reasons such as legacy code, time constraints, etc. Explaining to the audience how a design decision was reached and what factors contributed to the decisions, can help the audience gain perspective for why the design ended up as did, be it good or not so good. It can also explain why certain dependencies exist, identify border line cases that perhaps cannot be handled, and other ambiguities that the audience needs to know about.
Relationship to other information is another important factor. Information is often cumulative requiring you to first acquire a certain level of subject matter before you can learn more advanced stuff. Take for example mathematics. In grade one you first learned how to add, subtract, divide, and multiply before you were introduced to more advance operations. Knowledge about many technical subjects is no different. Thus explaining how the current information sets the stage for future topics can, at the very least, keep your audience interested, especially if the information being presented is primarily foundational for understanding more advanced concepts.
Grounding the audience is a similar issue. Often times we present information that will be consumed by audiences with vastly different levels of knowledge about the subject matter as well as those with different skills, knowledge, and backgrounds. Programming documentation for example, is notorious for diving straight into code examples under the assumption that readers understand what problem the code or API solves. In reality the readers are often turning to the documentation to learn just what problem is being solved before attempting to learn the code.
By backing up a step and first presenting background and foundational information that the audience may be familiar with, you can help ensure that all audience members have the same background information necessary to consume the forth coming information. And for those that do have the background information already, including this information helps to reassure those audience members that they’re starting in the correct place and that their level of understanding will be advanced by your content.
Finally, understanding the big picture is probably the most important factor. It’s very common to get bogged down in details especially in technical documentation. Therefore, it’s always good to continually explain how the information relates to the bigger picture. For example, an apparently small technical detail could actually play a large role in shaping system functionality or usage, so highlighting this in the greater context will help readers in their understanding of your technical matter.
There are probably many more reasons as to why explaining “why” is important but the factors highlighted above are probably the most common in technical writing. The bottom line is that your audience will be much better informed when you take the time to explain why the subject matter is important.
Now, if we could only redo our school courses again with more emphasis on the “why”!