Knowledge Article style requirements

Instructions for UofG Helpdesk Knowledge Base content creators to help you ensure that:

  • Your content is findable
  • Your content is readable and accessible to everyone
  • Your content is consistent with the rest of the Knowledge Base, forming part of a cohesive experience for students and staff

There are 5 steps to creating a Knowledge Article. Find out more about each step below, including detailed instructions.

Step 1: Check for duplicates

Before your write a new Article, check the Knowledge Base to make sure there isn’t already an Article on the same topic.

Only do what only you can do

  • In each Article, focus on one user need (or one closely related set of needs) that can only be covered by your team.
  • Don't duplicate the information provided by other teams, even if it's something your team is often asked about and has to refer people to.
  • Don't create Articles just to link to information provided by other teams.

Step 2: Write your Answer in plain text

Start with the words - the formatting, Categories, Keywords and so on can come later.

Write in a plain text editor - such as Notepad - take your time, and follow the instructions below to make your Answer as helpful and accessible as possible. As well as helping you focus on the words, writing in Notepad will make it easier to bring your content into UofG Helpdesk later, as the current text editor is not very user-friendly!


In your Title, signpost the answer to a person's question but don't write it in the form of a question. Instead:

  1. Describe the task you're helping people to complete. Use verbs.
  2. Start with the most relevant keyword followed by a colon ':'
  3. Keep your title short, so it doesn't lose meaning if the end gets cut off in search results


Question:        How can I share my calendar with someone else in Outlook?
Article title:     Outlook: Share calendars



To make your Answer as helpful and accessible as possible:

  1. Focus on one user need (or one closely related set of needs) that only your team can cover.

  2. Use the University's official tone of voice
    • Talk directly to your audience. Say 'You can...' and 'We will...'. 
    • Use the active voice rather than the passive. Don't say 'It is essential that the form is completed...' when you mean 'You must complete the form...'
    • Avoid using acronyms and abbreviations. If you really have to use them, spell them out the first time they appear.
    • Don't use jargon, slang or archaic terms.

  3. Put the most important information first. For guidance on this see Writing for the Web.

  4. Use short sentences covering just one or two points at a time. And keep your paragraphs short - single sentence paragraphs are fine.

  5. Use headings to break up longer answers and help people skim to find the information they need. Write headings in sentence case (Not Title Case).

  6. Use lists to help the reader parse information quickly.

  7. Break up instructions into numbered step-by-step lists, where each step is a single action of sequence of similar actions.

  8. Use descriptive text for links, ideally the title of the page you are linking to. Never use 'click here', 'download' or 'more' as link text. To find out more, see Writing for the web: Using Links.

  9. Consider users with visual or hearing impairments
    • Instructions 3, 5, 6, 7 and 8 above will also help make your Article accessible to people using screen readers
    • In addition, don't rely on colour or images to get meaning across
    • If your Article will contain images or video, write descriptions and captions for these now

  10. Follow the University Style Guide. This is the house style for for punctuation, spelling, terminology & more


More detailed guides

Step 3: Import your Answer

1. Create a new Article in the Knowledge Base

  1. Log in to UofG Helpdesk
  2. If necessary, switch to your Analyst role
  3. In the Workspace menu along the top, click Knowledge
  4. Click New Article


2. Type in your Title

As you do this, you may notice the Related items sidebar appear at the right of the screen. You can use this to check for duplicates, in case there's already an Article on the same topic, or to find related Articles you could link to from yours.


3. Import your plain text Answer

Do not copy and paste your text directly into the Answer field as this will cause you endless formatting problems! Instead:

  1. Click the Maximise button on the right of the Answer toolbar, to enter expanded view
  2. Click the Convert to Plain Text button, far right of expanded view toolbar
  3. Paste your content into the pop-up window
  4. Click OK

Step 4: Format your Answer

The Answer field supports HTML content including text styling, images, video, links etc. For most content creators though, the basic text editor will be enough.

The current text editor has some quirks, but you can work around these by applying formatting in the order recommended below!

8 steps to format your Answer

  1. Links: First make any links clickable:
    1. Select the link text
    2. Click the Hyperlink button (globe image)
    3. Paste in the URL
    4. The link will look now different to the rest of the text but that's ok, you'll fix it in a later step
    • Remember to use descriptive text for links, ideally the title of the page you are linking to. Never use 'click here', 'download' or 'more' as link text. To find out more, see Writing for the web: Using Links.Writing for the web: Links
  2. Email: Now make any email addresses clickable:
    1. Select the email address and copy it
    2. With the address still selected, click the Hyperlink button (globe image)
    3. Delete the https:// and type mailto:
    4. Paste in the email address
    5. eg
    6. The email address will now look different to the rest of the text but that's ok, you'll fix it in a later step

  3. Font: Select all and set the Font to Arial

  4. Font size: Set the Font size to 4 by clicking the A^ button twice

  5. Headings: If you have used headings, make these Bold and increase the size by clicking the A^ button once

  6. Lists: Format non-sequential lists using the Bullet List button

  7. Step-by-step instructions: Format these using the Numbered List button. If there are more than 2-3 steps, or the list looks cramped, insert a blank line between each step: click at the end of each line and press Shift+Return 

  8. Target text: If you're telling the user to click on something, or to type something in, make those words Bold


Preview your Article

At any time, you can go to the PREVIEW tab to see how your Article will look when it is published in the Knowledge Base.



You also need to ensure your content meets the new digital accessibility regulations for public sector bodies. As well as keeping your language simple and using the formatting indicated above:

  • Do not rely on colour or images to get meaning across
  • When using images or videos, provide descriptions and captions to make the information accessible to people with visual or hearing impairments.

Step 5: Complete other required fields


To help users find your Article in searches, you need to set good keywords.

  • Separate your keywords with commas
  • Don't include common, broadly applicable words like 'University', 'IT' etc
  • Include terms and short phrases that people might use when searching for your Article
  • Include common miss-spellings, shorthand and alternative words (e.g. Registration/Matriculation and MyCampus/My Campus)
  • Include keywords that you’ve already got in the Title and Answer – keywords are displayed as clickable links that are helpful to users looking for related Articles


User question:    How do I set up internet on my phone?
Article title:        Wi-Fi: eduroam auto setup
Keywords:          wifi, wi fi, eduram, edu roam, eurodome, connect, get online, internet, wireless, Android, iOS, Windows phone

Business Area

This is automatically prefilled for you based on your Team.


What you choose here will define who can see your article.

CollectionArticle visible to logged-in users with these rolesNotes
Staff & Student Staff and students (+public) You can disable Public access if appropriate.
Students Students (+public) You can disable Public access if appropriate.
Remember that staff often need to look things up on behalf of students, so 'Staff & Student' is often the better choice.
Staff Staff only You can enable Public access if appropriate.
Internal Staff in the specified Owner Team Useful for sharing internal documents with your team.
You can publish Internal Articles without approval/review.
Analysts Staff who have the 'Analyst' role Analysts Articles are not subject to full approval, only a peer review.
IT Analysts IT Staff who have the 'Analyst' role IT Analysts articles are not subject to a full approval, only a peer review.

Article viewable by public

This option is only available on articles in the Staff & Student, Student and Staff collections.

If you choose Yes then anyone anywhere will be able to view your article without logging in. This is essential if your intended audience includes alumni, prospective students, external colleagues, suppliers etc.

If you choose No, your article will only be visible to logged-in users with the roles defined by the Collection.

Category & Subcategory

These describe the area/theme of the Article and help users to browse for Articles. Category is mandatory; Subcategory is optional.

Provisional examples:

Category: IT, Money, Studying and Graduating, Library

Subcategory: Email, Holidays, Exams

If you need to suggest a new Category or Subcategory, raise a Request in UofG Helpdesk.

Owner Team & Owner

The Owner Team are responsible for the content of the Article, and the Owner is the person who submits it for approval. Both can be changed later if appropriate.

If necessary, you can create an Article and set someone else as the Owner.

Other content options


Linking to related Articles

You can include links from your Article to related Knowledge Base Articles. Links automatically work both ways, so once you link from Article A to Article B, Article B will also link to Article A.

Add a link

  1. Go to the RELATED ARTICLES tab
  2. Click Link
  3. Find an Article you wish to link to
  4. Click on it, then click Select

Remove a link

  1. Go to the RELATED ARTICLES tab
  2. Click to select the Article you wish to remove
  3. Click Unlink

Linking to the Service Catalogue

You can link directly from your Article to a Request or Report form in the Service Catalogue, so that the user can make the necessary Request or Report immediately:

  1. Login as an Analyst
  2. Open the Knowledge Workspace
  3. Search for Service Link List
  4. Open the Service Link List document
  5. Click the Maximise button on the right of the Answer toolbar to enter expanded view
  6. Browse for the form you want to link to
  7. Copy the URL and follow the instructions in Format your Answer above to insert the link


Only use an image where it is directly relevant to the Article topic and will be useful to your audience.

Make sure your image is accessible

  • Do not rely on colour or images to get meaning across
  • Provide a descriptive caption to make the information in the image accessible to people with visual impairments

How to add an image

  1. Save the image to your computer
  2. Open the image in an image viewer (Photos/Paint in Windows)
  3. Select and copy the image
  4. Go back to your Article, place your cursor where you want your image
  5. Right click and choose Paste


Only include video where it is directly relevant to the Article topic and will be useful to your audience.

Make sure your video is accessible

  • Include subtitles for any dialogue
  • Provide the same information in an alternative written format e.g. a transcript

How to embed your video

  1. Click the Maximise button on the right of the Answer toolbar, to enter expanded view
  2. Click the Source Edit button,second from the right of expanded view toolbar
  3. Enter your link to your source video, e.g. 
    <iframe src="" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen="" width="410" height="315"> </iframe>

    This example sets the size to 410x315 and shows the Youtube video:


Use attachments sparingly. Wherever possible, include the information directly in your Article.

When an attachment is necessary:

  1. Make sure the document meets accessibility guidelines. Never attach Word documents: convert them to PDFs so they can be accessed using a wider range of programmes.
  2. Scroll down to Add Searchable Document, below the Keywords field
  3. Click Upload
  4. Browse and select the file from your computer

All text in attachments will be indexed and included in Knowledge Base searches.

Reading list

Essential reading

Recommended reading

Available from the University Library