We recommend that you create some type of author's guide or style guide, even if you're currently only a solo writer.
There are all kinds of reasons for this, but the most basic is that having some kind of guide about how to contribute to the knowledge base will make it easier for everyone (including you) to create or update content with confidence and consistency.
We suggest adding guidance for:
Organization & categories
Provide a brief description and guidance for the overall layout:
- Where should authors put new content as they create it?
- If you have a rationale behind your content hierarchy, you can link to it here.
- If your authors will need to create new categories or subcategories, provide guidance on which category type(s) and display options to use as defaults.
- If you're not giving most authors the power to create new categories or rearrange content, give them information on who to contact to make those changes.
Articles
Identify which metadata fields are required or optional and how you'd like to use them:
- Are there cases where authors should use article short titles, or can they ignore this field?
- Are there cases where authors should use Internal titles, or can they ignore this field? (Suggestion: internal titles can be really useful if you have articles with the same or similar titles in different categories--you can add an internal title that includes a portion of the category or other identifying info to avoid confusion when using Link to article or other autocomplete searches.)
- Should authors use the Internal note field? If so, what kind of info should they include?
- If you're using tags, when and how to use them, how they should be formatted, and so on. If you're not using tags, explain why.
- If you're using search phrases, provide guidance on when and how to use them. If you're not using search phrases, explain why.
- Will you use the default Title Tag KnowledgeOwl automatically generates, or should your authors be adding a custom title tag? Provide guidance if so.
- We strongly encourage you to make Meta Description a required field, and provide some guidance on it. This helps with a number of display settings in categories/subcategories, and if you have public content, it's useful for SEO.
- If you're using article thumbnails, provide guidance on size, etc.
- If you're using article banners, provide guidance on size, etc.
- If you're using article templates, when should an author mark an article as a template?
- If you're using topic articles, when should an author mark an article as a topic?
- If you're using Reader Groups, what are the groups and when should they be added? (For example: are they added to top-level categories and then inherited, or only added explicitly to articles?)
- If you're using author teams, what is each team for; who belongs to them; when should they be used?
- When are New, updated, and video callouts appropriate? What is the default expiration date period and when is it appropriate to override that date?
- Are there ever cases where the additional restrictions should be used (to exclude from search results, hide from the table of contents, remove various abilities, etc.)? If so, provide guidance on when they should or should not be used.
- When are versions or version notes appropriate? See Version guidelines for what to include in this section.
- Should an author ever add explicit Related Articles? If so, is there any guidance on the number of articles or what type to add?
- If you're using the Contextual Help Widget (2.0), explain how to format the Recommend On Pages URLs and when it's appropriate to add URLs here.
Workflows
Document any authoring, review, auditing, or other workflows that your authors need to know about.
- Once an author creates new content, is there a review process before it can be published? Provide details and contact info as appropriate.
- Once content is published, what kind of auditing/updating processes are in place? If authors are directly responsible for these, give them full details; otherwise, a summary will do.
- If your knowledge base uses Comments, who's responsible for reviewing and approving/deleting new comments? How often should they do it?
- If your knowledge bases uses Contact Form, where do contact form submissions go? Who's responsible for responding to them?
Permissions and access
Document any processes for gaining or removing author access to the knowledge base.
- If an author doesn't have permission to change a setting or complete an action, who do they contact for help or to gain access?
- If a new author account needs to be created, who should be contacted/what is the process?
- Who is responsible for deleting an author or locking them out when they're no longer with your organization?
Style
Provide a full style guide for your knowledge base.
This can be a large project, but it will provide consistency across your authors and make it easier for more people to feel confident contributing to the knowledge base.
None of us here at KnowledgeOwl likes writing style guides from scratch. We recommend taking one of two approaches:
- Use a style guide template
You can do a search for templates that might work well for you.
Thursday Bram has a nice template available in .docx format on her blog, available at: Download My In-House Style Guide Template to Use However You Want. - Use a common style guide and only document additions or exceptions to that guide
For example, you can use something like the Google developer documentation style guide as a base, and then your own style guide references that and only provides more specific additions or exceptions to that guide.
Deanna Thompson gave a great talk on this strategy at Write the Docs Portland 2021:
