Writing IT Support Materials
Why write IT support materials? The main reason to do this is to help people get the most out of the IT systems that they need to use.
Here at ICT Training, we have adopted a Question and Answer format for writing IT support materials. By writing steps and actions and identifying the key questions, you can make sure that your audience won't misunderstand how to use an IT system.
Here are a few suggestions for writing Frequently asked Questions (FAQs) to get you started:
1. Choose the appropriate question type
If you are asking a question, then you need to answer it. There are at least 6 types of questions, each requiring different information to complete the answer. For example:
- Why - requires reasons
- How - should be answered with steps and procedures
- When - should be answered with times and dates
- Where - should be answered with locations
- Who - should be answered with names, title or role
- What - should be answered with details, examples, instances
2. Link to more information
If you need to explain what the system is, or you want to add information that you think is interesting, link to the additional information. For example:
| The answer to this question: |
Q: - How do I obtain a licence for XXXX? |
| Would be better written like this: |
Q: - What is XXXX and how do I obtain a licence for it? |
3. Links should be short
It is best to keep links short and not confusing or longer than one line. For example:
| Use: | installation instructions |
| Rather than: | www.sydney.edu.au/install%20%20instructions/microsoft/1-2-3-4-5%20%20excel/powerpoint/2007 |
4. Organise the material with your audience in mind
Organise your material in a way that is easy for your audience to grasp. You can do this by:
- Topic
- Top ten requests for information
For example: In the setup instructions for Outlook Calendars – you can include sharing calendars here as they are both part of the general topic.
5. Integrate additional questions
Anticipate questions that your audience may ask and put them in the text. And then show them where to get the information by linking to other resources. For example:
- Need more help?
- Need to know more? Try our web guide on...
- Want information on XXXX? You can find more information here...
6. Language
Language is very important, here are some guidelines:
| A. | Use Plain English |
| B. | Adopt the language of your audience |
| C. | Use the question in the first sentence of the answer |
| D. | Provide a one sentence introduction to the function, describing the function about to be performed |
Here is a list of the top eleven "most used" words:
| check | You check a check box (note this is two words) |
| click | Use click to describe mouse actions |
| dialog box | A type of window used to prompt a response, eg: Do you want to save changes? |
| display | Use display for things that appear, eg: dialog boxes |
| field | Use field for the part of the screen where you would type information |
| press | Use press for keyboard actions |
| select | Use select rather than choose |
| start | You start an application, dont use the word access |
| tap | Use tap rather than press to describe the touching of an object on a touch screen |
| type | Use type to enter text into a field |
| use | Use is the verb not "utilise", eg: You use the mouse |
7. Start with a verb
If you are writing instructions you should start each answer with a verb - ie an action - rather than a description of the possibilities.
Remember to keep it simple. Only one action per step.
Need more help?
If you want more advice or need someone to create support materials for you .