Skip to end of metadata
Go to start of metadata

Although there are many users working on Knowledge Base, we try to keep our articles looking consistent. This Style Guide is a reference for Knowledge Base editors and writers. It contains information on how to properly write, edit, and format articles within Experts. When writing instructions for Experts, common grammar rules apply. Just be sure to read over all instructions that you write to catch any errors you may have missed.

Making edits

Unless you are making very significant changes to a page, ensure that you de-select the check box next to Notify Watchers before clicking Save. This box is checked by default. De-selecting the box allows you to make a small change to a page without alerting anyone.

If you are making any major changes to a page, leave the box checked.

Page structure

Headings

One of the best ways to assist readers is to use well-organized headings and subheadings. According to GoodDocuments.com, "The goal is specifically not to see how much time you can get the reader to spend with your document, rather it is how little time they need to get all the information they need".  There are six levels of headings that can be used in a Experts article, which are summarized below. However, you will usually only use between one and four of them. For information on how to insert headings into wiki pages, see the How to Add Headings to a Page article.

Headings should not distract from the article. A style sheet exists for the look and feel of the wiki, and the heading styles built in (black, gray rule underneath) are the most appropriate for wiki pages. Do not change the style of headings. In addition, headings should contribute to making the wiki pages more accessible for all users. Do not use heading styles to emphasize text that is not a heading.

Headings can be used to create a table of contents for an article. Simply include the macro {toc} at the beginning of an article, and it will populate the table of contents based on text styled as a heading.

Do not put Bold formatting or color changes on headings. It often doesn't show up in the actual heading, but does in the table of contents, making the table of contents look strange.

Headings work a little differently in How-to, Reference, and Troubleshooting articles. See Knowledge Base Page Structure Guidelines for more information.

You can see what each level of heading looks like below:

Second-level headings

This is the highest heading level you should use in most articles. Use it for titles of major sections. Step-by-step guide and Related articles should be second-level headings.

Third-level headings

Use for subsection titles within a Experts article. Do not use both third- and fourth-level headings in an article, choose one; they are too similar in size.

Fourth-level headings

Use for titles of instructions within a Experts article. Also serves the same purpose as third level headings.

Fifth-level headings

Use for titles of instructions. Depending on the length and number of headings in the article, you may use fourth- or fifth-level headings for titles of instructions. Do not use both fourth and fifth-level headings.

Sixth-level headings

Use for subtitles or information you wish to draw subtle attention to, such as items in a list.

Table of contents

Adding a table of contents to a page helps readers find specific information quickly. If your page contains more than one heading, add a table of contents before any information on the page or after a brief introductory paragraph. Instructions on how to insert a table of contents are available on How to Add a Table of Contents.

Guidelines for the table of contents will differ for How-to, Reference, and Troubleshooting articles. See the Knowledge Base Page Structure Guidelines article for more information.

Number of steps

If you are working on an article with 20 steps or more, you should consider breaking down the steps into smaller sections. It is advisable to stay within the scope of 5-10 steps per section. Too many steps may overwhelm the user and create trickier organization on the wiki.

If the sentence is a statement or tells the user they have done something (for example, "you have now registered for your email"), it is not a step. A step will tell the user to do something, such as, "Click the Start button" or "Point to file, and then click Open." Do not include statements or exclamations in a set of numbered steps.

Writing style

According to Webreference.com, when you write for the Web, you should:

  • 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.
    As a follow up to the statement above, when writing a Web-based article, remember to separate the information into smaller bits; this makes navigation much easier for users. A good way to separate information is to use the appropriate heading style and include a table of contents.
Tables are not appropriate for displaying step-by-step instructions and should be reserved for presenting tabular data.

When writing material for the Web, it is necessary to keep information flowing and orderly. Users tend to access the Internet for quick information and don't want to search through a lot of text to find that information.

When submitting articles to Experts, writers and editors should adhere to the Web writing guidelines.

The university has an Editorial Style Guide that provides information on the style and usage guidelines for common words and references related to the university.

Action-oriented writing

To best help the user understand how they can use a program, you should write instructions in a task-oriented manner. The following is an example of poor instructions:

The File Menu

Use the file menu to save your documents.

Why is the above example poor? It does not list where the file menu is located or how to save the document once the file menu is opened. If a guide that discusses menu items in necessary, it should be a Reference article, not a How-to article. A better example would be:

Saving a document

  1. From the top menu, click File > Save as.
  2. Choose a location to save your file, then click Save.

Word choice and grammar

When writing for Experts, writers and editors need to keep in mind basic grammar rules and remain consistent from article to article.

Order of instructions

Write in a logical order. If you want a user to find something on the File menu, don't write, "Click Save on the File Menu." The user will go to the File menu first, so write the instructions in that way.

Example: On the File menu, click Save.

Example: Click on Insert Image.

Terminology

When writing about a program, use the terminology given by its developers. For example, when referring to the Microsoft Office 2007 and 2010 toolbar, use the word "Ribbon".

Do not use "highlight" when talking about selecting text or an item. Because "highlighting" is an actual function for word processors and PDF readers, using it to mean selecting text is confusing. Use "select" when discussing text, buttons, items that have been selected, etc. 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, and the button is clearly labeled (Submit, OK), do not use the phrase "click the OK button." Items that are labeled don't need re-labeling, and this just creates extra words. Instead use "Click OK."

Personal pronouns

To better relate to Experts readers, writers can 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.

Contractions

Use of contractions on Experts is accepted; however, contractions should not be used in formal writing.

Serial comma (Oxford comma)

Use the serial comma in the appropriate situations.

Example: Britney Sales logged in to Experts and edited the pages on Apple, Installing Hardware, and Microsoft Word 2007.

Formatting guidelines

Editors should also remain consistent in formatting and layout when creating Expert articles. The following formatting guidelines are based on recommendations from the Microsoft Manual of Style for Technical Publications.

Text formatting

When to use bold

When writing or editing instructions, bold the words or buttons that readers will click on or interact with (a link, a dropdown, etc). 

Example: Click Start, point to All Programs, point to Microsoft Office, and then click Microsoft Office Word 2010.

Example: 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.

Example: To access the Missouri State University website, type www.missouristate.edu.

Italicize names of windows or dialog boxes.

Example: The My Computer window opens.

Keyboard Keys

Capitalize the titles of keys on the keyboard. Keys that should be pressed simultaneously should be combined with a + sign.

Example: Press CTRL+ALT+DELETE to log in.

Callout boxes

Information

The Information box contains additional information that is not necessarily of high importance but still useful to the task at hand.

Notes are by-the-way or additional information and should be formatted as shown here.

Please consider the information you present in these callout boxes. If the information is a warning, it should not only be included in the warning box, but it should also be included in the text. Also consider the rainbow effect of having all of these items present on one page, as this can be distracting. If the formatting is not necessary, don't include all of the items. Instead, consider making a checklist of things to consider or creating a separate section for very important information.

Warning

Warnings are more critical information. If there is any chance of personal injury or hardware malfunction, place a warning in an Expert article.

Using warning alerts readers that the information given is more critical than the information given in a note or information box, such as a risk of injury or loss of files. Warning notes should be formatted as shown here.

Note

Notes are not as critical as warnings, but they do contain very important information.

This calls special attention to the area. This information is serious, but not dangerous.

Lists

Numbered lists

When writing a set of instructions or steps, use a numbered list. However, be aware that you are not able to change the style for the numbered list in Experts and spacing will remain the same. Numbered lists can cause trouble with respect to images included in a set of instructions; it is best to review a page after you have created a set of instructions to view whether your numbers have started over or your images are indented with the numbered list. 

Do not use numbered lists for items that are not steps or do not need to be listed in order.

Bulleted lists

Bulleted lists:

  • help break up information, making it easier on the reader. If it is logical to add items to a list, do so. Do not add long paragraphs to bulleted lists.
  • should be punctuated correctly. If it is a sentence, place a period at the end. If it is one item, do not.
  • have similar formatting issues to numbered lists, and you cannot alter the spacing.

Colors

The use of colors other than black should be limited for text. This is done to minimize confusion (for example, blue text is often perceived as a link) and maximize accessibility (not all users can see all colors). Emphasis can be added by using bold and italics. The default link color should not be changed. Do not change the default colors.

Images

Images often make a page easier to read and understand. However, if your image is too big, too small, not aligned properly, or fades into the page, it will only hinder the page's information. The following guidelines apply to images in Experts.

Size

Attempt to keep images no larger than 500 pixels in width. Smaller images are perfectly fine and don't need to be resized to 500px. Large images obscure text and take over the page. Very small images (especially with text) are difficult to read and take up space without providing useful information. It is easy to resize an image to 500px by clicking on the largest box on the pop-up image editor. 

Call-out boxes

When using a call-out on a picture, we use a simple red box (see above). Please do not use arrows, circles, or different colors. We recommend Jing for a simple, easy-to-use photo editor, and it's free!

Border

You will typically need to add a border around the image so it does not blend in with the page. If a border or very distinct edge already exists around an image, do not add a border around the image.

Alignment

Images should be aligned with text. If an image is very large, you may want to center it on the page.

Videos

When creating videos to add to Experts, we recommend uploading to YouTube. Instructions about How to Add a YouTube Video to a Page are available.

Videos should be created with formatting and grammar guidelines in mind. Do not create overly conversational videos. Your videos can be more conversational than your writing, but do not add in slang, etc. that would make the video unprofessional and inappropriate for work.

Creating references

To avoid plagiarism, editors writing for the Web need to reference all the information they gather from other sites. When using outside sources for Experts, 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.

References

 


For questions or comments, contact the Computer Services Help Desk
HelpDesk@MissouriState.edu
417-836-5891