Select Page

When creating an article you should ask the following questions

  • What type of information is it? (see templates below)
  • What is an appropriate title?
  • Who is your target audience? (Are you writing this for fellow SIT Staff?  Service Desk?  Everyone? End-Users?)
  • What  language is appropriate? (What terminology should you use?)
  • What categories or tags should you use?
  • Does the audience have to perform tasks?

What type of information is it? – using the templates

We have templates for the following types of  knowledge. choose the most approriate and use them.

  • Standard Operating Procedures (how to documents)
  • Information
  • Service Descriptions
  • User information

Title

Pick a good title as this is the first information a user sees when they search the knowledge base.

A title should briefly describe what the article is about and incude as many keywords as is appropriate. This will allow users to recognize what the article is about and should reduce time taken to search for the most relevant information.

Remember that the entire explanation doesn’t have to go into the title. You can use the summary to give the user additional information about what is in the article.

Language

Along with the title, the summary or introduction is what people will use to quickly decide if the article is useful. Always include who the article is written for as well as:

  • For a SOP (tutorial or how-to) article: Give a brief summary of what things can be learned.
  • For an Information article: Give a brief explanation of the feature.
  • For a Service article: Give a brief summary of the service and possible uses.
  • For a User article: Give a brief explanation of the user’s department, position and research.
  • For a troubleshooting article: Give a brief summary of the problem and its symptoms.

Try to build information from simple to complex while trying to keep the information needed by most people near the top. So a simple, common solution would usually come before a complex or edge-case solution.

When writing step-by-step instructions be careful to include all the actions needed to complete the task. If, for example, you have to click “OK” after selecting a preference in order to move to the next step, be sure to include clicking OK as part of that step. Some additional things to consider:

  • There are always multiple ways to achieve a result. We should always pick the most user-friendly way – using the graphical user interface and menus when possible.
  • Use full sentences when describing how to access the user interface.
  • Include expected results when giving instructions (for example, Click OK and the window will close).

For a general audience use an active, conversational style when you write (e.g. use “If you want to access your home drive…” instead of  “If a user wants to access their home drive…”)

Some guidelines on general computing terms:

  • The Internet is uppercase.
  • Website is one word.
  • Log in and log out are verbs. Example: “Log in to the website.”
  • Login and logout are nouns (usually used as adjectives). Example: “Click the login button.”
  • Use email instead of e-mail.
  • The plural of CD-ROM is CD-ROMs.

Categories and Tags

There are a number of pre-defined Categories that organise the information.  The idea behind this is that they will change rarely, if at all.  Setting these will help people when they manually search for articles.  Categories are typically larger scale groupings e.g Software/Hardware.  This is so that all articles will fall under atleast one Category.

Tags allow for a more dynamic content grouping.  You can choose from the most common tags listed on the right hand side – or create your own!  Try to be consistent, although the Knowledge Manager will try to keep tags from getting out of control.  Use as many tags as you feel is appropriate.  Please do check to see if a tag already exists and is similar to the one you want to use – this will help us keep searches relevant.

Visiblity

Ask yourself how visible this document should be. Visibility defines audience – who you want to share this with – for example everybody, just IT staff (e.g ITS and Science IT)  or internal only (Science IT staff).
Assume you are writing for a general audience rather than one very familiar with computer techniques and terminology and will be best served with step-by-step instructions.

Skip to toolbar