Best practice in technical manual design
Our observation is that often technical writers focus excessively on the content itself. The final product is less effective than it should be because of inadeqaute consideration of:
• Assumed knowledge or skills of the part of users that just doesn't exist; for example baseline technical skills, the ability to source relevant information, "obvious" background information that actually isn't obvious....
• The context in which the materials will be used; A4 paper content for use in outside weather-affected locations... the need is for an urgent problem-solving decision, but the answer is buried in chapters of text....
Perhaps the biggest challange though is that content is mapped around the perspective of the Subject Matter expert (SME), not the users. The two can be quite different. SMEs already have deep knowledge, and can draw linkages between widely disparate pieces of information. They get frustrated with 'simple' information such as overviews and structures of content. Ironically, it is exactly this level of information that document users need in order to be able to make sense of the material.
For us, this all means that the template design process needs to include:
• A review and/or articulation of assumed skills
• Business Process Mapping of the processes to which the content will be applied
• An Information Architecture for the document that is driven out of pragmatic use cases
• The incorporation of best practice elements, for example the use of icons, text block layout, and so on.
Good document design also involves tradeoffs between competing interests such as ease of maintenance versus ease of access. The challenge is that these priorities are often skewed in favour of the things that matter to those responsible for creating the document, rather than those using it. Getting the right group together at document design stage is absolutely crucial.
Posted by PhilGaring at
05:59 PM
