“Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances – so software usually needs them all.
And documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from each other.”
—Daniele Procida, “What nobody tells you about documentation.” Divio. Accessed: November 12, 2018.
Probably applicable to any kind of documentation process you need to replicate, not just for software.
Barbara Minto‘s “The Minto Pyramid Principle” is a how-to guide for writing concise reports in a management consulting firm that has been around for years. I wrote a one sheet summary of her book over a decade ago that I still sometimes find to be a useful aid for writing. While it might be overkill for most writing we do, it is still a useful reference.
First Things First, Subject/Predicate
- What is the subject you are writing about?
- What is the question you are answering in the reader’s mind about the subject?
- What is the answer?
Make It a Story
- What is a situation where the Subject/Predicate can be illustrated?
- What problems complicate the situation?
- Do the question and answer still follow?
Find The Key Line or Take-Away
- What new question is raised by the answer?
- Will you answer it, inductively or deductively?
- If you answer inductively, what is your plural noun?
- Dramatize the main idea using imagery.
- Imagine a doer – for analysis and writing.
- List all the points you want to make, then find relationships.
- Ideas at any level must always be summaries of the ideas below.
- Ideas in each grouping must always be the same kind of idea.
- Ideas in each grouping must always be logically ordered.
- Always try top down first.
- Use the Situation for thinking through the introduction.
- Don’t omit to think through the introduction.
- Always put historical chronology in the introduction.
- Limit the introduction to what the reader will agree is true.
- Be sure to support all key line points.
- What is the problem?
- Where does it lie?
- Why does it exist?
- What could we do about it?
- What should we do about it?
- Introductions are meant to remind not inform.
- They should contain the three story elements.
- Length of introduction depends on reader and subject.
- Never use only one element for a heading.
- Show parallel ideas in parallel form.
- Limit to the essence of thought.
- Don’t regard headings as part of the text
- Introduce each group of headings.
- Don’t overdo.
- Question the order in a grouping – time, structure, or ranking.
- Question source(s) used in the problem solving process.
- Question the summary statement.
- Question your expression.
Structures for Evaluation
- Financial structure – consider strictly financial issues.
- Task structure – focus on how work gets done.
- Activity structure – focus on what needs to happen to create problem.
- Choice structure – bifurcate choices.
- Sequential structure – combination choice and activity structure.