OIT has compiled these general guidelines for writing knowledge articles. Following this style guide will help create consistency across our articles.
General Formatting Guidelines
- Use Headings in Knowledge Articles
- Using Lists in Knowledge Articles
- Short Description Guidelines for Knowledge Articles
The following formatting guidelines are based on recommendations from the Microsoft Writing Style Guide.
Colors, Font Size, Font Family
- Do not change the default colors.
- Do not change the default Font Family
- Do not change the default Font Sizes
When to use bold
When writing or editing instructions, bold the words or buttons that readers will click on or interact with (menu, dialogue box, dropdown, checkbox, etc).
- Example: Click Start, point to All Programs, then Microsoft Office, and then click Microsoft Office Word 2010.
- Should be: Click Start > All Programs > Microsoft Office > Microsoft Office Word 2010.
Be consistent throughout the article.
When to use italics
Italicize anything the reader will type. Italicize names of windows
- Example: The My Computer window opens.
- Example: Enter password.
Keyboard Keys
In general, use sentence capitalization and standard abbreviations for key names. Keys pressed simultaneously should be combined with a + sign.
- Example: Press Ctrl+Alt+Del
Personal pronouns
Use "you". All other personal pronouns such as me, they, I, us, she, and he should be used minimally for good reason or not at all.
Use Active Verbs
- Passive: The dashboard is activated by clicking ON.
- Active: Click ON to activate the dashboard.
You can determine passive voice by the using the "Zombie" test If you are able to add “by zombies” after the verb and it makes sense, you are most likely using passive voice.
Writing Style
- Write conversationally.
Write articles as though you were speaking to a friend. You want the reader to feel comfortable with the instructions, not intimidated. If you are writing instructions, it is okay to use the pronoun "you" to address the user who will be following your instructions; this manner of address is actually preferred for most instructional documentation, as it puts the user in the driver's seat. However, it is usually better to avoid using personal preferences when writing a set of how-to steps, so "I's" should be less often used.
- Write small paragraphs.
When writing for the Web, try to use as few words as possible. It is daunting to read through a large paragraph, and users will have to search to find what they need. If appropriate, use a numbered list or a bulleted list. If it is not appropriate to use a list, break your paragraphs into manageable (but logical) chunks.
- Separate the Information.
When writing a knowledge article, remember to separate the information into smaller bits; this makes navigation much easier for users. Tables are not appropriate for displaying step-by-step instructions and should only be used for presenting tabular data.
General Terminology
- Do not use "highlight" when talking about selecting text or an item. Use "select" when discussing text, buttons, items that have been selected, etc.
- Use "highlight" only when you are discussing the highlighter tool.
- Use "highlight" only when you are discussing the highlighter tool.
- When writing the word "email", do not insert a hyphen between "e" and "mail".
- Avoid using the phrase "click on." A simple "click" will suffice.
- Windows: A window will include minimize, maximize, and close buttons.
- Dialog Boxes: A dialog box is a window that requires specific input from the user (OK, Yes, No, Submit)
- There will be a button or buttons to press for the user to complete an action.
- Dialog boxes do not have minimize/maximize buttons.
- Buttons: If you are asking the user to click a button, do not use the phrase "click the OK button." Instead use "Click OK."
- Contractions: Are generally allowed but keep in mind that contractions should not be used in formal writing.
- Serial comma (Oxford comma): Use your best judgement when deciding to whether or not to apply the serial comma. Remember Pluto.
Jargon
Jargon can be tricky. While there are no specific rules, consider your audience before using jargon that might not be public knowledge. For example, VoIP, IAM, JAMF, NOC, and VPN are common terms within our environment, but not necessarily outside our environment. Especially when creating Public knowledge, assume novice exposure to jargon. Define technical terms and write clear descriptions and assume not everyone has the same level of expertise with every technology. If the jargon is an acronym, consider spelling it out the first time.
Creating references
To avoid plagiarism, authors need to reference all the information they gather from other sites. When using outside sources, editors should create a reference section in the article. A citation should be placed after the information from the outside source is used. When clicked, this citation should link to the online article referenced.
Citation format
Citations should follow the Chicago Manual of Style. For example, when citing a Web site:
Google. “Privacy Policy.” Last modified March 1, 2012. http://www.google.com/intl/en/privacypolicy.html. Retrieved April 10, 2012.