Overview

It's important to maintain consistency in creating knowledge articles so that users know what to expect. Consistent outline and consistent formatting create a professional, easy to access, and easier to learn from content.

Additionally, there are certain publishing-related steps you need to take to make sure the article gets to the support portal correctly.🔥Make sure to read the very last section in this document about setting Content Access Levels on support articles.

Style and Formatting

Poorly formatted documentation casts shade on the entire knowledge article. If the author couldn't be bothered to learn the basics of writing to communicate their knowledge effectively, can they be trusted to have actually provided their knowledge? Style and formatting are critical, and must be treated as such.

Best Practices

Below is a list of best practices I expect my writers to follow.

Always Use Built-In Styles

When creating a heading, NEVER simply make the font larger and make it bold. Instead, ALWAYS use Paragraph Formatting to indicate whether this is a level 1 heading (Heading 1) or lower. The only exception to this is when you simply must highlight some text inline to emphasize that some information is different from other information. 

Never use underline simply to underscore something, as underlines are universally understood to be hyperlinks. Conversely, do not remove underlines from hyperlinks simply for stylistic purposes - your hyperlink will likely be overlooked.

Use numbered lists instead of bulleted lists

There are cases when bulleted lists make sense, but they are rare. When you use numbered lists, it's easy to refer to them later. Using bulleted lists leads to such atrocities as having to explain that the user should "follow instructions starting on the 8th bullet from the bottom", instead of just saying "go to step 64".

Use heading levels to segment content

Splitting a block of text into H1, H2, and more if makes sense will create a sense of organization for your content and make it easier for people to understand where they are in the document.

Use sentence-casing in lower headings

Don't capitalize every word in headings level 2 and below. Capitalizing every word in H1 headings is OK - use your own discretion if it starts to look odd.

Use built-in heading level styles

Do not, under any circumstance, simply enlarge text and make it bold to make it a heading.

Use Block Styles to indicate text intent

For example, make sure to use Computer Code to indicate that a block of text is software code or script. Explore what Styles are available. If you need to make some text larger, use Big style, if you need to make it smaller, use Small. The reason for this is that Block Styles are relative to the Normal style, whereas setting text size (for example) directly, makes formatting absolute.

The difference is this: if you make text size absolute, for example, it'll remain true to your setting even if the surrounding text changes. For example, if we decide that Normal style is 16 point where it was 12 point before, your larger text that was 14 point will remain 14 point, and will now be actually smaller than the rest of the Normal text. If, however, you make your text Big, when Normal style changes, your Big style text will get proportionately bigger.

The same applies to changing fonts. Fonts should only be changed through Block styles and not directly, unless there's a really compelling reason for it.

Use images, animated GIFs, and Videos

🚫 Make sure no client-specific or irrelevant information is displayed

For animated GIFs or quick videos, ScreenToGif is a FANTASTIC, free piece of software that will let you do quick animated Gifs or videos, with overlays and captures of mouse clicks. I can't recommend it highly enough. Most of the time it's faster to do the thing the client asks for and record it as you're doing it than to explain the entire thing in text.

➡️Download ScreenToGif and donate to the man. It's worth it.

You can also use a video editor to create videos, but that's going into another territory that we won't cover here. One does not simply walk into video editing.

Make all images the same size

All images showing similar amount of detail should be the same size. Go for 1024x768 px. Maintain consistent ratios of width to height. If you must have images of different sizes, make all widths be the same as that creates a more streamlined appearance.

Use emoticons

Windows has a convenient shortcut (Windows key + period) to show you a window where you can select / search emoticons. Use it. The blue arrow in an earlier section was inserted that way.

Emoticons are a great and easy way to draw the reader's eye to something, they're a lot easier to work with than custom images.

Be aware of customer environment differences

Make sure to identify explicitly portions of your instructions that will need to change for the customer's environment.

Demonstrate intent with style

What does this mean? For example, if you're going to say that customer-specific strings will be shown in [bracketed highlighted bold text], use the highlight and bold text to show what it'll look like. It's entirely possible that the user's display will render your example in some other way, so at least they'll be able to see what you mean.

Do not rely on style alone

As in the example above, notice that I also used square brackets to indicate the customer-specific string. This is important for accessibility reasons (people see color differently), and also not everything is always in color; imagine printing the text on a B&W printer and trying to find that yellow highlight.

Using symbols will help people see your intent much more definitively than if you just use color.

Do not use sentence-end punctuation in lists or headings

...unless it's an exclamation or some other exception

Use AI voice-over in videos

Download "Clipchamp - Video Editor" from the Microsoft Store and learn it. It has a great feature that allows you to type up some text and have an AI voice read it to voice-over your video. This is significantly better than recording your own voice. Pick Sara as your voice-over, she's super-friendly.

➡️ Download Clipchamp - Video Editor from the Microsoft Store
 

Re-read and edit your work

Twice. You'll catch things that'll surprise you.

Pre-pend article name with client shortcode

Unlike support cases and tasks, Knowledge Article titles aren't automatically updated based on the client. To make it easier to identify to whom the article applies, start the article with the shortcode of the account - assuming the article is targeting a specific client.

Documentation is Work

Documentation is hard and provides a LOT of value. Put appropriate amount of time into it, and bill for it if it's part of resolving a problem. Upfront documentation means next time there's a similar issue (or even the same issue), it'll take less time to resolve. If you have questions as to whether something is billable, you know who to ask.

Verify Article Attributes before Publishing

Review the following properties (available on the CONTENT and SUMMARY tabs).

1. CONTENT
   1. Keywords - comma-separated keywords that can be used to find the article
   2. Description - optional, but if there's something about this article that needs to be said that isn't in the body, say it here.
2. SUMMARY
   1. BASIC SETTINGS
      1. Internal - No. If you set it to Yes, it will not show up on the Portal
   2. PUBLISH SETTINGS
      1. Subject - pick appropriate subject. Look at other articles to get an idea, or ask, if you're not sure.
   3. RELATED INFORMATION
      1. Categories - pick as many categories as apply to the article. Create a new one if you don't see it if you really feel you need an extra one. Consider relationships between categories when you create one and pick the appropriate parent.
      2. Content Access Levels - this is critical to set correctly. If you leave the CAL as "Default", the article will appear on the Portal for EVERYONE to see. Obviously, for client-specific articles, this is an issue. See below for a more detailed discussion of Content Access Levels.

Set Correct Content Access Level

Each client gets their own content access level. If you're writing an article for a specific client, make sure you remove the Default content access level and add that client content access level to the article. If you're writing an internal article, add inWorks LLC as the content access level.

If a client signs in to the portal, they will see general access articles, and also articles specific to their environment - keep this in mind if writing articles about a sensitive process that is not suited for all client users; in this case, set content access level to inWorks LLC, leave it blank, or set Internal field (above) to Yes so the article does not get published to the portal.

If you're writing an article for general consumption, leave the content access level as Default. After publishing the article, it will be available on the support portal. To confirm, you can go to https://support.atin.works and you will see your recently published articles under Most Recent Articles column.