Article Writing Guidelines

When creating content in your knowledge base, we encourage you to come up with a consistent style and layout that can be used as a guide for your editors, to help them produce consistent looking content across your site.

You should come up with your own style guidelines, and write them up somewhere that editors can easily access (such as in an internal knowledge base article)

We've listed some general guidelines here to help get you started, although you can change any of these you need

Fonts & Text Size

It's generally best to use a consistent set of fonts and text sizes across your articles. Inconsistencies can look out of place if your readers navigate from one article to another and find completely different font sizes and styles in use. This can be distracting.

Colors

Similarly, with colors, it is often best to define and use a consistent palette of colors for text, headings, bullets and other content across your site. You ideally want your readers focused on the important content you've written for them, not on how the content is styled.

Images

Quarterly Sales Spreadsheet The use of images and illustrations are often a great and easy way to add visual appeal and interest in your articles. That said, try to stay consistent across your articles with the amount, style and themes of the images you use. Again, defining some guidelines for your editors may be helpful in this regard.

Quarterly Sales Chart Within the GoGoWorx article editor, there are several options available when displaying images or embedding videos into articles, so some guidance regarding consistent styling may be helpful here too.

They say a picture paints a thousand words. This proverb is true within knowledge base articles. To break up monotonous volumes of text, visually convey information, or communicate something that may be too complex to describe in words, including charts and illustrations can be extremely beneficial .

By way of example, consider a quarterly sales review; certainly you could write about that performance and how it relates to other quarters, but wouldn't it be much simpler to show a spreadsheet, a graph, or even better, show both to readers, then simply reference those images from the text?

Consult Marketing

Your knowledge base is also one of the touchpoints between your company and your users and customers. When developing a styling guide, you should consult your marketing team, so that they are aware of what you're doing, but also to allow them to make suggestions so that the knowledge base style and theme is consistent with your corporate image and the messaging you are using across other interfaces, such as your public websites, marketing and product collateral.

Since Marketing teams generally have experience working with consistency, graphic design and look & feel, it makes sense to include them in this decision.

Periodic Styling Changes

As with any other customer-facing material, such as websites and product documentation, your knowledge base should be able to get fresh style applied periodically.

If you have selected one of the Account Types that enables Theme and Style Customization , you can create and maintain your own custom CSS styles and classes. These can be used to change the look and feel of visual elements on a global scale. For example, you can change the style and color of font that is used for your articles, including headings and paragraph spacing. You can also style the way images and tables are displayed.

Changing Styles

This level of customization means that your marketing or design teams can easily change the look and feel to match changes being applied to other public-facing material.

Also, when Theme and Style Customization is available, you can custom-design the header at the top and footer at the bottom of public-facing pages. This means you can match the styles used in other places as well as including logos, links and any other custom features your team wish to include.

Writing Style

The writing style you choose for your knowledge base should be consistent across your articles too, in the same way that writers choose a style, diction and tone when writing a book. The overall sentiment of your articles should aim to be helpful, never condescending or confrontational.

You should also not assume your readers are fluent in any technical terminology you use. Indeed, you should try to reference those terms' meanings whenever possible to remove such ambiguity. See the Glossary feature, which explains how to add hints for defined acronyms to your readers.

Article Links

As you can see in the paragraph above, there are several links to externally referenced web pages as well as other articles within the knowledge base. Providing these reference links is vital to providing readers consistency and context around what they are reading.

specifically providing links to other articles in your knowledge base within the bodies of your articles allows readers to retain context, while navigating your documentation without needing to explicitly search for things. This keeps them engaged and feeling motivated to use your knowledge base.

You should include as many links to related articles as possible. You can also control whether those links open new browser windows, or are opened in the current window, depending on how you want to lead their navigation.

Related Links Another helpful feature you should use is to create a list of Related Articles for your readers. These are context-specific to information contained within each article.

When editing an article, you can create references to related articles that you think may be helpful to readers. This both allows users to stay focused on your article without needing to repeat information written elsewhere, while also engaging them by providing richer content and allowing them to navigate to related information if they choose.

File Attachments

A very helpful way to interact with your readers is to provide them content they can download. This may be pdf documents, sample code, spreadsheets, or zipped files containing something related to the text contained within the article itself.

When editing an article, you can add File Attachments whenever needed. Note that the size, type and number of attachments permitted is defined within the Admin Settings .