Table of Contents
Write a short description of the article, Who it is for, what it’s about and why it’s useful. This should not be more than 2 sentences. E.G: This article is for implementers who need to create a competency framework, it will describe the process to follow and link out to relevant documents. This will help you get started quickly and provide you all the templates needed to complete this task.
How to write up a Knowledge Base Article
- log on to the wiki site so that you can write up your article
- If you don’t have an account, reach out to (Bodo@gooru.org)
- Click on Knowledge Base > Add New Article
- If this is your first time opening it, there may be a quick guide overlay for you to read.
- The start of your article should have the following three items at the top of the page:
- A Title that describes the article – this will also be the name of the page
- A Table of contents that is auto-populated with any anchors you later add to the article, like headings. To add the Table of contents, click on the + icon (Add Blocks) at the top left of the page, > Scroll down or search for “Lore Table of Contents > add it to the article.
- Add a Heading, and a Paragraph block for the general overview/description of the article. You can add clicking on the + icon (Add Blocks) at the top left.
- Now you can write up your article using the following guidelines:
- Keep it simple!
- Use the Heading Block for each new section (headings will be auto-linked in the Table of Contents)
- Use the Paragraph Block for text
- Use the List Block for processes
- Use the Image block for screenshots and Gifs
- Use other blocks where required, but don’t get tempted to get to fancy. These pages should be easy to ready by people, and in order to get indexed properly, should have a simple structure.
- When describing processes, Say what the process is for in one simple sentence, then use numbered bullet points for steps, using a List Block. These may get indexed by Google if they are setup in this format. Here is an example from a Google knowledge base:
- Where feasible, record a quick Gif (no more than 15 seconds) to accompany a process. Especially for those processes that are on Navigator tools. Gif’s can be easily created using one of these apps:
- When finished with the article, choose which headings/sections you want to add in the Table of contents, don’t choose too many. Keep it simple.
- To add an anchor, click on the block you want to add the anchor to
- Click on the gear icon at the top right to open up the settings for the block
- Scroll down to Advanced
- In the HTML anchor field, enter a word or two — without spaces — to make a unique web address just for this heading.
- List any related articles at the bottom of the page, by adding in their IDs or slugs (URLs) separated by a comma.
- When finished, complete the Article settings as follows and publish the article for review.
- Click on the Gear Icon at the top right of the article
- Make sure you are on the Document settings tab
- Open up the Article Categories section, and select all the relevant Categories this article should appear in.
- Open the Article Tag section, and add relevant Tags to the Article, refer to the Article Tags Guide
- Open the Discussion section, and Untick the “Allow Comments” checkbox. Any comments and discussions will be handled by MatterMost, our community chat/forum tool.
- Click on the “Publish” button at the top right of the post, and then click on “Submit for review”
- Notify an Editor that your Article is ready for review. For now, email (firstname.lastname@example.org)