The article provides guidelines on how to write a Knowledge Base article.
Title
The title is very crucial as this is how the users will actually find answers to their questions. Give a descriptive title that makes it easy to understand what is discussed in the article. It should not be too long and should include keywords.
Subtitle
Give a short description of the content of the article and what problem this will analyze and solve.
Note that there is a word limitation for this section in Hubspot Knowledge Base.
Main body
1. Topics to be covered
Spend some time thinking about what information you want to communicate through this article and if this should be a new article or part of an existing one.
Check articles discussing similar topics to make sure you do not duplicate content.
2. Build the structure
Structure the article in an easy to read way, e.g. describe the problem, explain the cause, provide steps to solve the problem. End the article concluding on the solution.
Always bear in mind the purpose of writing this article. Troubleshooting articles follow a different structure than articles explaining how to accomplish a task.
3. Writing
Use simple language and write so that an average customer can follow. Try to prevent long and complicated sentences. Assume basic knowledge. Terminology and abbreviations should be explained at the beginning of the article (or the first time this word is used). Make sure to use the terms that are frequently used.
Maintain a consistent style, use active voice to make the instructions clear and direct, use present simple tense to provide instructions. Address the user in the second person (you instead of the user).
Bullet points, numbered lists, and visuals facilitate comprehension. Use them when they are relevant. For example, use a numbered list to provide step-by-step instructions on how to perform an action. Use the colon after a complete sentence to introduce a list of items.
If the text following the bullet point is a complete sentence, it should begin with a capital letter, while a period at the end is technically required but is not absolutely essential. What matters is that you need to stick to the same approach within the article so that it looks more professional.
When you are using an image, make sure that the background is in contrast to the illustrated item.
Link the article to other ones that are relevant and will provide more details on the topic. The text of the link should be descriptive of where the link directs the user. Avoid using click here or check this article.
4. Quality control
After writing always read the article and make sure that it makes sense and that the format is proper.
- Make sure that there are no typos.
- Check your grammar. Make sure that you used complete sentences with proper grammatical structure.
- Check the spacing between the paragraphs.
- Confirm that your article follows a structure, a logical order.
- Make sure there is no repetition.
- Check screenshots resolution when the article is published. If it is blurry, make a new screenshot.
5. Review
Depending on the audience and topic of the article there are different rules:
- Public article: Get review and confirmation of the reviewer before publishing
- Internal article introducing a new process: Get review before sharing with the team
- Internal article documenting a known issue: No review required. Once shared with the team, everyone can edit or add more details.
6. Sharing articles
Make sure all articles you are working on are tracked in Clickup. Only share the new article with the team once it is finished and published. To share a new article with the team create a subtask "Read new article about ..." and tag all the members of the team. People can remove themselves after having read the article.