The first half of this year has been a challenging one for me. Whilst I and my team have steered through plenty of documentation challenges for the three major product releases this year, one challenge has been common for all the projects: to get ourselves understood correctly.
As I talk about technical communication – and I’ve done that quite frequently in the last year – I continue to search for simple yet efficient techniques to help create simpler yet effective documentation.
For this post, I will talk about what I mean by “getting understood correctly” by breaking the concept into two logical sections – say what you mean and mean what you say. In relation to the topics of minimalism and rhetoric, I’ve drawn this method-oriented comparison to help improve comprehension.
Mean what you say
In the projects we delivered, the single-most criticality related to structuring of information. (Just to draw the line further, information, here, relates to facts, observations, and data served; and, structure is how that information was provided in our documents.)
I would like you to note that the structure of most of my posts is derived straight out of my personal rule book. Mostly, all my posts carry the same Premise-Rationale-Example-Conclusion (PREC) format. I use this format to make a definitive value proposition.
I’ve also noticed that my readers pay more attention to what I say if I begin with the point (or premise). Also, this makes it easy for me to think along the lines of the thought as I continue interacting – thus, it helps provide a flow (or structure) to the thoughts.
Structure, as we just discussed, is one aspect. Note that you should also provide facts and observations to support your structure. My PREC structure suits me, because I provide examples that support my premise. And, based on these examples, I either oppose or support my premise – and, hence provide the conclusion.
Say what you mean
This section is about stating things clearly. It’s easier said – I agree that it is difficult to write what you intend to. However, there is a one-line solution: Always stick to the rules of grammar. Your words are linked to the actions of your readers. Therefore, their correct comprehension (and consequent action) is a clear indicator of the effectiveness of your content.
However, there is another link, which is more apparent – the subject-matter link. In technical writing or instruction designing, it is important to link actions and their consequences. For example, when we write instructions, we write the consequence before actions. This improves user understanding.
Now, for a moment, let’s go back to the PREC structure. Note that to state things clearly, you must present your point in a technically and grammatically accurate manner and provide conclusion based on your premise. But, to clear the things already stated, you must present information in a structured manner.
It is noteworthy that providing conclusion isn’t mandatory. Just as the helping verbs are at times not required in a sentence, the conclusion too is at times not required. In such cases, try to link actions and consequences.
Some munching in the end
I conclude that the communication derived from the points in the Say What You Mean section are result oriented,whereas the communication derived from the points from the Mean What You Say section are information oriented.
As I previously said, I’ve purposely kept the Premise and Conclusion in the Say What You Mean section, whereas the Example and Rationale in the Mean What You Say section. This makes categorization easy to remember, follow, and cross check.
But, these are only some points that I gleaned based on my analysis. Also, I still am evaluating their effectiveness in preparing documentation. I’ve used the following parameters to judge if it the comparison drawn is doable and sharable:
- Ease in understanding the need (or purposes) of documentation
- Time consumed to create the desired (required?) content
- Number, and complexity, of modifications in the methodology based on personal (or internal) evaluation or external feedback (if available)
I would be happy to read your feedback on the post.