Illiteracy is, sadly, something that can greatly affect people’s lives. According to The Literacy Trust, less than one per cent of adults in England can be described as completely illiterate and approximately 16 per cent as “functionally illiterate”.
There are various articles on the Web that indicate how people live with their illiteracy:
- They depend on people (relatives or the kindness of strangers) to read and explain things for them.
- They recognise places and the location of things based on colours or shapes.
- They often have to trust people aren’t scamming them.
- They generally work within more limited boundaries, keeping to a consistent routine.
- They often memorise how they completed a task last time.
If we produce a product but do not supply user instructions with it, the user has nothing to read, whether they are literate or not. The user has to fall back on coping mechanisms similar to those used by people with illiteracy. They can function, but they would do much better if they had something to read.
It’s a fair bet that the introduction of the new Troubleshooting information type into the DITA 1.3 technical authoring standard will affect how all Technical Authors write troubleshooting topics, regardless of whether they use DITA or not. That’s because the proposed elements for troubleshooting topics make good sense, and it offers a standardised approach to writing these types of topics.
According to the Oasis DITA standards committee,
Troubleshooting topics provide descriptions of and solutions or workarounds for problem situations that users might encounter. Users refer to troubleshooting information to understand what condition or event generated their problem situation and to find out what they need to do to recover from or work around a problem, or to prevent a recurrence of the problem.
The user would see a topic that looks roughly like this:
Continue reading “Writing troubleshooting topics”
Imagine you are an IT manager for an organisation that has been implementing new IT systems. You have now reached the point where you need to create and document the new IT policies and procedures. The organisation already has some general policies for IT in its staff handbook, but you need to provide more detailed information on how to use the organisation’s IT efficiently and securely.
For example, the staff handbook tells staff that customer information must be treated confidentially and only approved communication channels must used. The IT policy and procedures document will provide more detail – that web email services (such as Yahoo Mail) must not be used to send customer information, because they often store a copy of the email even if you have deleted your sent message.
The best approach would be to have some sections in both the staff handbook and the IT policy document. In other words, the same content in different documents. Otherwise, staff would need to have two manuals open each time they wanted to check they were doing things correctly.
If you use Word, you’re likely to do this by coping the text from one Word document and pasting it into the other Word document. The problem with this approach is that when you make a change to the text, you need to remember to paste any amended sections into the other document. This make it very difficult to create customised variations of documents, such as cut down versions for managers or new staff, branch-specific versions etc. It becomes unmanageable.
One of the benefits of using some of the alternatives to Word is you can embed a piece of information into multiple documents. In a similar way to how you can use the same image in lots of different web pages, you can use the same chunk of text in lots of different documents. The advantage of this approach is that in the future you’ll only need to change the source, embedded chunk of text when it’s time to make a revision. That piece of text gets updated automatically (or semi-automatically) in all the documents that use it.
In the ‘Whispers’ episode of BBC Radio Four’s Digital Human programme, Aleks Krotoski explores how rumours spread both online and in the physical world.
As an example, she looked at how two people were able to spread a rumour that a tiger was running loose in London during the 2011 riots.
Aleks claims we are now in a world of misinformation. For organisations, this means they now have to pay attention to any misinformation or rumours about their products and services, an activity that is often called ‘reputation management’.
Seven minutes into the radio show, Nicholas DiFonzo of the Rochester Institute of Technology states groups believe rumours typically because there is a lack of information from official channels, they don’t trust official channels, or because their friends believe it. People use rumours to figure things out.
This means if there is a gap in information, then rumours may fill that gap. For this reason, it’s important organisations publish their Help files or equivalent on the web, so that there isn’t any uncertainty over what your product can and cannot do. If you don’t, whatever Google serves as an alternative source of information will fill in the gap.
Where people might not trust the official marketing content, they are more likely to trust the technical, instructional information. It’s seen as more ‘truthy’.
What do you think?
Please share your thoughts, using the comments box below.