Comprehensibility: Building Understanding
Documentation Assumes Reader Already Knows Everything; Reader Does Not
A comprehensible technical document follows a logical structure. Every topic builds on preceding topics. If a new concept is needed, it must be introduced beforeusing it. This applies at every level—from the document structure down to individual sentences.
The Four Steps of Explanation
Every concept you explain should follow this pattern:
Definition
What is the thing? Give a clear, concise definition. Don't assume the reader knows what you're talking about.
Example: "A variable is a named storage location in memory."
Assumption/Theorem
What can we do with it? What are its properties? State the key facts or capabilities.
Example: "Variables can store different types of data and can be modified during program execution."
Explanation/Proof
Show how it works. Provide examples, demonstrate the concept in action, prove your assertions.
Example: "Here's how to declare and use a variable: int count = 0; count = count + 1;"
Conclusion
Summarize and reinforce. The human mind needs repetition to commit to memory. Unlike computers, we need to be told several times.
Example: "In summary, variables are named storage locations that hold data you can read and modify throughout your program."
The Golden Rule
"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."
This isn't redundancy—it's pedagogy. Tell them what you're going to tell them, tell them, then tell them what you told them.
Quick Check
What is the correct order for explaining a new concept?