This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.
Minimalism is a widely accepted and influential methodology in technical communications, but it is not a simple method to understand or apply. John M. Carroll’s two books on minimalism: The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skills (1990) and Minimalism Beyond the Nurnberg Funnel (1998), provide the best source for the ideas behind the theory.
Minimalism begins with understanding your users—in particular, how they need to use your software in order to accomplish their specific business goals. Designing content that really addresses this problem is notably more difficult than simply documenting the features of your software. But tackling this problem can help you develop much more usable content!
“Minimalism” – It’s seemingly a simple word, says Barbara, but it’s surprisingly difficult to get your head around it.
Barbara talked about her path to minimalism. She says she has some “special expertise as an impatient user”, which gives her a special insight into minimalism. This got a laugh of recognition from the audience. She also gave us a useful list of influences, including books, articles and methodologies. These include DITA, content strategy, Information Mapping, Every Page is Page One by Mark Baker, and more.
Update on 14 June 2014: The above paragraph previously stated, erroneously: “She also gave us a useful list of references to books, articles and methodologies that have influenced minimalism.” I have now changed it to say, “She also gave us a useful list of influences, including books, articles and methodologies.”
Minimalism is a theory of learning developed by John Carroll at IBM in the 1980s. He used the term the Nurnberg Funnel to describe the way people learn. They’re not passive when learning. They want to drive their learning experience, based on what they already know and what they want to achieve.
His study found that when people are handed a comprehensive set of instructions, only approximately 1 out of 20 follow the instructions from beginning to end. The others jump around, do their own thing, make mistakes, get lost, and have trouble finding their way back. People like to do things their own way.
In response, Carroll decided to design tutorials that start users immediately on meaningful and realistic tasks – things they needed to do. He also wanted to reduce the amount of content, and make errors and error recovery less traumatic.
So instead of comprehensive coverage, he aimed for selective coverage based on the user’s goals.
Barbara used the terms “minimalist design” and “systems design” to compare the two approaches. (At first I was not quite sure why the term “systems design” was used here. But later during the presentation, I think I know: it denotes a manual whose structure is based on the structure of the user interface it’s describing, rather than on user tasks.)
Marta talked through these points of minimalist design:
- Brief orientation
- Prerequisite tasks
- Learn by doing, start straight away
- Modular, self-contained topics
- Support error recognition/recovery
We looked at an example of a legacy document, which was organised to match the menu structure of the user interface. Barbara described how she reorganised the document along minimalist principles. She started by identifying the key user roles (booking officer, investigator, administrator) and their key tasks (create booking records, search for new records, etc). The new guide was then organised on sections based on tasks (use the import queue, create inquiry records, create booking records, etc).
Questions from the audience
At this point, a member of the audience said that the minimalist guide would be more of a quick-start guide, but a comprehensive user manual is still required. Barbara’s answer was that a system-organised reference manual is typically not used very much. Users typically want to find their information within the context of the key business task. If it’s important to explain specific elements of the screen, do it as part of the business task.
A number of related questions arose, which Barbara answered authoritatively and clearly. One audience member made the point that you could start with the minimalist guide and allow people to drill down to the more detailed information. Barbara also said that part of the role of technical writer is to point out what the primary focus is: serving the users’ needs based on usability studies. We don’t need to document everything that other people tell us to document.
Psychology of learning
Barbara related the principles of minimalist design to the psychology of learning, which shows that we are complex, emotional beings, not machines that run scripts. We do things for complex reasons, without necessarily understanding the reasons ourselves. We need to act, even to struggle, in order to learn and to retain information. People may even be too busy learning to spend much time on the instructions.
Developing minimalist documentation
Examine the system you’re documenting, decide where it’s not intuitive to use, and help the user with those areas. Discover the user’s mental model, and find out if it matches how the tasks are carried out in the system. If not, help orient them to the system. Find the common error situations, and help users through them.
I’ve never consciously used minimalist design, although I’ve attended a few talks on it through the years. I feel that some of the principles have rubbed off on me. This talk helped crystallise and solidify the concepts and practise of minimalism for me.
I’m attending Tekom tcworld 2012, in Wiesbaden. Jang Graat is about to present a session called, “Write less – say more. The added value of minimalism”. I’ve read quite a bit about minimalism, and am looking forward to hearing Jang’s ideas on applying the methodology to make things easier for our readers.
This is the blurb for Jang’s session:
In the internet age, users are swamped with information. Instead of telling users what you know, you should literally put yourself in their position and figure out what they need to know. And then see how you can make that information available as concise and clear as you can. After the initial extra effort, it will make your job, and your user’s lives, a lot easier and more productive.
The principle of minimalism is fairly simple, and is not changing much. Jang plans to give us the basic principles and what they mean.
We started by watching a clip of a Vin Diesel action movie, where couldn’t find in the user manual what his car could do. Jang says Vin Diesel is our typical user. The typical user is in an emergency. They need one answer to one question. And if they don’t find the answer, the world is going to end.
Many of us are still writing lots of documentation that people will never need. Our users are suffering from information overload. A lot of it is useless. The good stuff is hidden by layers that most people will never use.
Put there only what the user needs. That’s minimalism.
John M Carroll at IBM took the minimalist practices, already applied in interior design and other disciplines, and applied them to technical documentation.
WilliaM of Ockham (philosopher in 13th century) said you shouldn’t introduce a new element unless you really need to. This is Ockham’s razor. Minimise the number of assumptions you make, and build your theory around that.
You make sure you have the minimum set of tools that you need for a certain situation. The last four words are important. Compare the set of tools a repairman takes up onto a roof. He won’t take his torch, for example, if it’s daytime.
Advantages of minimalism
- Improves the signal-to-noise ratio: Removes noise, maximises signal
- Minimises cost
- Minimises effort, for the technical writer, and for the user trying to find information
- Minimises support effort
- Maximise clarity
The most important thing is: Topics.
Typically, documentation answers 3 or 4 questions at the same time. For example, let’s say you want to add a row to a table in Word. Find the topic in the help – it typically starts by describing tables, then tells you there are a few ways to add a row, and also tells you about columns.
Rule of minimalism: One topic answers one question.
The most important question you can answer is: how do I do this. If you want to, you can add extra topic(s) that describe how stuff works.
Give your content a very clear, recognisable structure. The user can get used to this structure, and then find information easily. Example: Recipe books. This is a minimalist practice, because it minimises the user’s effort.
Amount of content
Minimise the number of words you write.
Remove repetition, for example don’t repeat the title text in the introduction of the topic. Don’t use words like “first”, “then”.
Use annotated diagrams where possible, instead of lots of words to describe the location of things.
Control your language. You can use a specific type of controlled English, or do it yourself. This minimises ambiguity.
Use separate steps, not joined by “and”, unless the user has to do two actions simultaneously.
Maximise safetyl For example, in documentation about machinery, safety is a big issue.
On the other hand, don’t exaggerate. Exaggeration has the effect of devaluing the message. That is unsafe. (The machine industry has a strict classification of the severity of messages.)
Don’t have too many warnings, errors, cautions. That is not safe.
Jang described how minimalism maximises efficiency, making it easier to meet deadlines. Production becomes more efficient, because there’s less to produce. (Think, printed manuals.) You minimise the time people need to find information, thus maximising their efficiency.
Focus on users
This is the main point that Jang wants to make: Focus on the users. This is the main lesson in any approach to minimalism. Put yourself in their shoes when you decide what to write.
Jang has a pleasant, restful speaking style. His slides were pleasantly minimalist. Thanks Jang.
Minimal text. Big friendly arrows. Partial screenshots. Is this one example of what a simple document looks like? How to Edit the Atlassian Developer Documentation.
Over the last few months our team has been asking itself what constitutes simple documentation. As any technical writer will tell you, answering that question is not a simple matter! In July I wrote about one product manager’s response to the question: What makes simple documentation. A number of people responded with some very interesting comments on that post.
Is this a good example of simple documentation?
Now here’s an example of a document I’ve just written. It is aimed at a specific market (community developers who want to contribute to our documentation) and describes a fairly simple task flow (how to find the edit button on the documentation site, save a draft and then publish your changes).
My aim is to get people started as quickly as possible and give them enough pointers that they can figure out the rest themselves. The readers are a savvy bunch. They know what they want to do, and have used many different types of editors. So I’ve gone for:
- Minimal text.
- Bold sequenced steps.
- Partial screenshots, with enough context to orient people.
- Big friendly arrows pointing to the relevant control.
Here’s how the document starts.
1. Log in
- If you don’t yet have a username and password, please sign up for the Atlassian Contributor License Agreement.
- Click the login link and follow the prompts.
2. Search for or click through to the page you want
Use the search box to find the document you want.
Alternatively, click through to the page you want:
Click the ‘Docs‘ tab.
Click through to the page in the left-hand navigation panel.
3. Hover near the title and click the edit icon
- Move your cursor to the top left of the page’s content panel. The edit icon (two crossed pencils) will appear.
- Click the pencils.
- Make your changes. The wiki is running Confluence 3.5 with wiki markup.
The rest of the page
And so on. If you like, you can take a look at the real page: How to Edit the Atlassian Developer Documentation.