Make it SIMPLE

• Find the core idea and present it first.
• Use the remaining content to support the core idea.
• Eliminate everything else.

To illustrate this, Made to Stick describes a problem the US Army had a with orders: By the time commanders in the field received the order, it was outdated and the commanders had to choose between ignoring the order or implementing an order that no longer made sense.

To solve this problem, the US Army improved its communication protocols in 1980 by adding a commander’s intent (CI) to each order. The CI is “a crisp plain-talk statement, [to] the top of every order, specifying the plan’s goal, the desired end-state of an operation.” As a result, field commanders could act on the intention of the order, its core idea, despite changing circumstances in the field.

The CI sounds a lot like the DITA shortdesc element writers put at the beginning of their topic, just below the heading.

• For a procedural topic, use the shortdesc to “explain what the task information helps users accomplish, the benefits of the task, or the purpose of the task.”
• For a conceptual topic, use the shortdesc to, “introduce the concept and provide a concise answer to the question ‘What is this?’ and in some cases ‘Why do I care about this?’ If the concept is unfamiliar, you can start with a brief definition.”

I know some of you feel ill when you hear DITA mentioned in tech writing discussions. Even if you’re not using DITA, you can’t deny that it makes sense to give your readers a clear statement of the core idea at the beginning of your topic.

Doing this helps your reader to quickly “sniff” whether this is the information they are seeking so they can decide to read more or continue looking.

The bad

The opposite of identify the core idea and putting it at the top is:

• Burying it somewhere else in the content.
• Presenting multiple competing ideas.
• Including tangential or irrelevant information.

We don’t do these things on purpose. They happen because we are either blind to them or lack the time and energy to revise them out of existence.

The ugly; revising to good

For me, words are like stepping stones that mark a path through a garden of information. When I revise a topic I’m working on, I reread the words and retrace the path I laid out earlier.

As I do this, I notice odd spots:

• If I notice a misplaced stone, I move it to a better better spot or toss it out.
• When I find a gap, I fill it with a stone from somewhere else or I generate a new stone by generating the idea that belongs there.

Usually, these changes create new odd spots in the path. So, with each move or fill, I spend a bit of time working it into place and reworking the surrounding material. I keep doing this, developing my thoughts and moving them around until I feel like I’m done.

Then I come back the next day and see a whole new set of things that are out of place. This is more of a problem with blog posts like this one than with technical content, whose structure is more defined.

The trouble with “eliminating everything else” is that I’m still generating new ideas (stones) when I’m revising. To solve this, I have to force myself to stop creating and focus only on removal. This isn’t easy if I’m attached to interesting by irrelevant ideas in the content. The solution is to save off a copy of the document before I start cutting away the excess. That way, when I finish the current topic, I can review the copy and use the interesting bits to generate new topics.