Latest posts by techwriter (see all)
- How NOT to Look for a Writing Job (1) - January 22, 2017
- Hazards of Poorly Written Technical Documentation - December 26, 2016
- Get an ‘A’ on Your Next Research Paper With These 6 Simple Steps - November 28, 2016
By D Harland
There are a number of well known factors that impact the effectiveness of documentation, both as an aid to learning and as a guide to getting the job done. An approach to documentation known as minimalist has been around for many years, but remains little know outside specialist interest groups. The approach produces clean easy to read documentation. Manuals and guides produced using the approach have a much higher probability of being useful and therefore of being used.
Why do people use documentation?
Peoples use of any tool is driven by their need to achieve certain goals. When people use documentation it is almost always in a very active way. The documentation is referenced because they need to do something now. Information gathering, knowledge building and understanding of mechanisms behind how processes are achieved is to most readers a secondary issue.
When people go to a piece of documentation for the “how to” information and find it difficult to extract, they are much less likely to go back and read the explanations associated with it. So documentation must satisfy the primary need or it will never get the chance to fulfill the secondary.
Most readers have low expectations of documentation. Every time they have difficulty extracting information from a manual or piece of documentation, it reinforces this mental picture and expectation that documentation will not meet their needs.
Documentation needs to fulfill two roles:
- The procedural, how do I do this?
- The declarative, the explanation as to how and why things are done the way they are.
These two roles appear mutually exclusive and therefore the material needs to be separated in order that the reader can get at the information they require.
How do people use documentation?
The first thing to appreciate is that people will often read documentation as a last resort. This is often a deliberate policy on their part, brought about through:
- The assumption that there is nothing new to learn;
- That there are quicker ways of finding the information;
- A preference to ask someone who does know.
Documentation is read in order to perform some task and the reader brings with them a set of expectations. It has been shown that people try to integrate what they are learning with what they already know, and this process can inhibit the reader. Children do not bring the same ingrained experiences with them and therefore tend to passively accept the system and follow the instructions as they are. It is this difference in approach that gives rise to the all to frequent comment, if you want to sort that get one of the kids.
When people read documentation and try to learn they create reasons on the fly and anchor these in their prior knowledge. In summary people read documentation and manuals in the same way that they try to learn systems, through exploration.
How do people search documents?
Research suggests that in only 25% of cases were appropriate indexes and contents lists used to locate information. However in 90% of all cases the preferred method is to thumb through the pages scanning for information. This explains in part why online documentation and help present users with so many difficulties.
Problems with documentation
Manuals tend to contain extensive explanations, with very narrowly focused examples and practice exercises. This structure does not fit the active time pressured need to know now requirement of the reader. Even when the reader follows the documentation closely, minor errors can cause the reader to go off on time-consuming tangents. And often the reader does not know what they have done to create the error situation. Most documentation does not address the issue of recovery from minor errors, which is particularly important for the novice user. There tends to be too much material in manuals that acts as camouflage for the information being sought.
The idea behind the minimalist approach is to present the user with documentation that:
- Removes all repetition.
- Provides practice exercises;
- All information not related to the procedure of a task is removed or drastically cut down.
Since people in general and novices in particular do not read documentation it is probably better to spare them and cover only the critical specifics.
How to create minimalist documentation
The emphasis is on the creation of documentation that is simple to use, can be understood by novices and can act as a reference aid to more experienced users.
Chapter headings should be task oriented and the table of contents list act as a simple index. The contents should be labeled in a way that the novice user can understand.
Chapter headings and notes should be on the right side for odd numbered pages and on the left for even numbered pages. This allows for the user to thumb through and still see the relevant headings. Specific actions should be explained once and then simply referred to.
Questions should be posed via prompts encouraging the user to actively think about what is going on, on the screen.
David Harland is a an experienced IT executive and freelance consultant. David has held senior IT posts in the software industry, publishing and banking. Over the past 12 years David has worked as a freelance consultant advising public and private sector organizations on IT strategy and maximizing investment in IT. For more information visit http://www.jamespatrick.ltd.uk.