4. Comprehensibility
In the complex process of reading, the step following the ‘tokenisation’ of the text is the actual ‘parsing’ — understanding what these symbols and their relations mean. A clear separation of these two steps however can not be made.
A great portion of comprehensibility issues already was covered when we discussed recursion above.
Recursion is the enemy of understanding
An understandable technical document always follows a logical structure. Any topic discussed is based on the preceding topics. If a new concept is needed for the topic at hand, it needs to be introduced before using it in dealing with this new topic. This holds true for any level of detail of the document at hand, down to individual sentences.
The basic steps are:
1. Definition
2. Assumption/Theorem
3. Explanation/Proof
4. Conclusion
Of course, the classic structure of ‘thesis, antithesis, synthesis’ may be more appropriate for certain topics, such as discussion of architectural decisions, but generally the above sequence is exactly what we need.
On the ‘atomic’ level of a sentence, its logical structure is governed by raw grammar. Therefore, a good working knowledge of grammar is absolutely necessary for getting our ideas across to the reader as we mean them to be.
4.1 Definition
In this segment of the document, all terms and concepts necessary for the following should be defined. In some cases, reference to previous material in the document is sufficient. Referring to later sections is to be avoided at all cost. If it should for some reason be necessary, the definitions may be placed in endnotes or a glossary at the end of the document. This should be clearly indicated at the very beginning of the document. Footnotes are not intended for the purpose of definitions. They are a place for further explanations or material of a ‘non sequitur’ nature2.
4.2 Assumption/Theorem
The task of this segment is the presentation of the idea or concept this particular document or part of a document is supposed to deal with.
Make a simple and clear cut statement of where your argument starts and what will be the intended outcome. No why or how should be given here. The why should be clear from earlier portions of the document, the how is the subject matter of the next section.
In a user’s guide, this is where an indication of the function to be explained should be given.
4.3 Explanation/Proof
This segment of our document deals with giving justification for the idea put forth in the previous section. It may be of purely argumentative3 nature — say, defending architectural decisions — or come close to mathematical proof in style. In the case of a program implemented practically, this is the place for explaining the workings of it step by step. Or in the case of a user’s guide, to explain the interface and sequence of steps necessary for completing a given task.
4.4 Conclusion
For the document to be successful, a conclusion must be given, reiterating the above steps in a shortened form. This will reinforce the impact of the material presented on the reader. The human mind, unlike a computer, needs to be told several times before committing to a certain course of action.
Repeat the central message of what you write several times. The human mind is not at ease when confronted with a ‘fire and forget’ type of message.
Now, without looking back at what was written above give a summary of what was said in section 4. It won’t be repeated here. Can you recall the topic of the last subsection of section 4? What number was that subsection?
See?
No comments:
Post a Comment