Clemson Knowledge Article Style Guide

Knowledge articles (KAs) provide customers with clear, consistent, and accessible technology answers to their questions.

Important: Keep formatting as simple as possible:

• Always observe the editor's default font throughout the article including headers.
• Use lower case letters except for section headers which can be all upper case.
• Use bold for items to be clicked on (do not use quotation marks for this).
• Follow the simplified formatting rules described later in this style guide.

To link from one HDKB article to another one, use this link replacing the XXX with the article number:

• https://ccit.clemson.edu/support/kb/?id=XXX

The remainder of this document is organized into main topics, which also can be followed as basic steps for completing an article:

• Complete your KA field entries
• Apply paragraph and text formatting
• Observe writing style conventions

COMPLETE YOUR KA FIELD ENTRIES

CHOOSE AN ARTICLE-TYPE TEMPLATE

You can start your article by copying and pasting one of our short starter templates.

Important: The templates are located at the end of this document. A template exists for each of the article-type options (see above).

If you do not use a template, keep these guidelines in mind:

• Do not repeat the title in the article.
• Begin with a one- or two-sentence summary of what the article will accomplish for the user.
• Create a basic outline for the points you want to cover.
• Use step-by-step instructions that relate to the title of the article.

APPLY PARAGRAPH FORMATTING

Writing articles will be easier if you keep formatting as simple as possible.

Always use the editor’s default font for all paragraphs, including headings.

To visually organize your article’s content, use these paragraph formatting conventions:

• Start your article with a brief summary or introduction in regular (non-bold) body text (do not repeat the article’s title).
• Use heading paragraphs to indicate sections or subtopics. Format headings in boldface uppercase (all-caps). Do not use larger fonts for headings.
• Try not to use second-level headings. If unavoidable, format them in boldface title-case (each word capitalized).  
• Use bullets to indicate lists of two or more items.
• Use numbering to indicate steps.
• Indent body text paragraphs to indicate second-level content.
• Use blank paragraphs sparingly (mainly to emphasize breaks in content and section headings). The default settings include built-in spacing for each new paragraph. 

OBSERVE WRITING STYLE CONVENTIONS

Note: For authoritative information on grammar and punctuation, see the The Chicago Manual of Style, which is available online (subscription-free) to all Clemson University network users.

These writing style conventions include guidelines for:

• General writing
• Hyperlinks
• Pictures
• Tables
• Text formattting and punctuation
• Preferred action words and terms
• Preferred examples of writing

General writing guidelines:

• Assume your audience has basic technical knowledge. For example, you likely won’t need to explain how to open a program, locate a menu item, or use a drop-down box.
• Assume your audience is broad. Faculty, staff, students and researchers at all levels of technical expertise will need to follow your instructions with minimal assistance.
• Write in complete sentences, including a subject, verb and object.
• Use active voice, present tense, second person (you, your).
• Use simple language, omit non-essential words and avoid technical jargon.
• Use bullet lists when priority or order of precedence are not important.
• Use numbered lists to write instruction steps.
• Keep instructions simple; each step should express a single action. Break complex processes into simpler tasks, each with its own step-by-step instructions.
• Some steps may include multiple field entries or require subtask instructions. Organize these types of information in second-level lists.

Guidelines for hyperlinks:

• Include links to provide users access to additional instructions or information.
• If a resource you plan on linking to does not yet exist, indicate the link in parentheses as follows:  (future link:  Link Name) .
• Important: To be accessible, a link’s text must describe the targeted information. Don’t use links that say only “click here.”  For example:
  • Original:
    Complete the following steps or click here for the Automatic Setup Tool for Outlook.
  • Preferred:
    Complete the following steps or use the Automatic Setup Tool for Outlook.

Guidelines for pictures:

• Use pictures (screenshots and illustrations) only when they are essential to a reader’s comprehension. For example:
  • An instruction involving multiple entries in a dialog may justify including a screenshot of the dialog.
  • Most simpler instructions, such as navigating through levels of a menu or clicking a button, are easier to follow without a visual distraction.
• Avoid captures of an entire screen. Try to focus on the window, dialog or area of a screen associated with the instruction.
• A good rule of thumb for maximum picture width is 7 inches or 600px. Place each picture on separate a line, in a left-aligned paragraph that contains no text.
• To improve accessibility, include a concise description beneath the picture in italics.
  Important:  This practice is necessary because the Cherwell editor does not support the preferred accessibility rule of including alt text for all pictures.

Guidelines for tables:

• To improve accessibility, try to avoid the use of tables.
• If you do need to use a table, keep it as simple as possible, without merging/splitting cells, rows or columns.
• Since tables can be difficult to format in the Cherwell editor, you may prefer creating  them in Microsoft Word. If you do, only use Word’s Normal paragraph style set to 12pt Calibri with 6pt space after.

Guidelines for text formatting and punctuation:

• When describing user interfaces, applications and systems, use bold text to indicate: screen, window or dialog titles;  on-screen commands;  menu options;  field titles and user entries; keyboard key strokes. For example: 

From the main menu choose Employees to display the Employees submenu dialog.

• To avoid confusion with hyperlinks, do not use underlined text formatting.
• Use italics to give special emphasis to a word or phrase in your instructional content. Do not use italics to indicate a user interface feature.
• End all complete sentences with periods, including those in bulleted and numbered lists.
• Use a colon at the end of phrases or sentences that introduce bulleted or numbered lists.
• For special information associated with a subject (notes, tips, warnings, etc.), begin a paragraph with a boldface label ending with a colon. For example:
  • Note: This window displays by default when you open the application.
  • Important: If you do not click Save, all of your entries will be lost.

Preferred action words and terms:

• Check or Uncheck 
  Use to indicate the selection status of a check box field.
• Choose 
  Use to indicate selection of a feature or menu option.
  Example:  Choose File > Print from the menu.
• Option > Option
  Use unbolded greater-than sign (>), with spaces before and after, to separate options or features in a navigational sequence.
• Click or double-click or right-click
  Use to indicate selection of a link or button on the screen.
  Example:  Click OK.
• Download 
  Use to indicate transfer of a file to your local system.
  Example:  Download the executable named Symantec Endpoint Protection.
• Drop-down menu
  Use to indicate a field with multiple preset options.
• Enter
  Use to indicate text that is typed into a field.
• Log In or Log Out
  Use to indicate the submission of credentials to access an application or system.
• Open
  Use to indicate the display of an application or file.
• Press
  Use to indicate the selection of a keyboard character or physical button.
  Example:  Press the Enter key when you have made your selection.
• Key-Key
  Use unbolded hyphen, without spaces, to indicate a multi-key sequence.
  Example: Press Ctrl-Alt-Del to reboot the system.

Examples of preferred writing:

• Be concise and simple.
  • Original:
    Type user data at login screen and click on the OK button to continue.
  • Preferred:
    Enter your username in the User Name field and click OK.
• Use active voice.
  • Original:
    The Print screen is displayed by the system.
  • Preferred:
    The Print screen displays.
• Use present tense.
  • Original:
    The User Settings dialog will display on the screen.
  • Preferred:
    The User Settings dialog displays.
• Use a second person point of view (you, your).
  • Original:
    Type in the user’s ID and password.
  • Preferred:
    Enter your username and password.

Article-type templates:

If you are writing a knowledge article (KA), one of the templates below may help you get started. Find the best article-type for your situation, then copy and paste it into your new KA.  

Article type:  Informational / Concept   

Title examples:  Subject  or  What Is/Are Subject?  

Short opening paragraph:  This article discusses...  or  Title/Subject is a....

(Explain in sentences, paragraphs (a) How the subject works (b) What the subject means (c) how the subject fits into other systems, processes, services or a category thereof.)

(Use subheadings and bulleted lists for longer discussions. Provide background that helps readers understand essential information about the subject. Provide an example of the subject or a link to an example.)

Article type:  How-To / Workflow / SOP / Error Message

Title examples:  Verbing A Subject  or  How To Verb A Subject  or  How Do I Verb A Subject  or  What To Do If If You Get A Subject Error Message

Short opening paragraph:  This article explains how to title/subject…  or  This article includes the steps for title/subject....  or  The reason for performing title/subject task is…   

To perform the task, follow these steps:

1. Text of step 1 goes here.
   (Can include a brief description of the result of this step...)
2. Text of step 2 goes here.
   (Can include a brief description of the result of this step...)
3. Etc.

Article type:  Problem/Symptom / Reference  

Title examples:  Types Of Subject  or  Configuring Subject  or  Troubleshooting Subject  or  Error Messages for Subject   

Short opening paragraph:  This article includes supporting/troubleshooting/quick reference information you may need to reference while (write a description associated with your title/subject).

(Present the information with bulleted lists or tables or in problem-resolution pairs.)  

Article type: Frequently Asked Questions (FAQ)  

Title example:  Subject FAQ   

Short opening paragraph:  This article includes frequently asked questions and answers about (subject).

Q:  (Question…)

A:  (Answer…)

Article ID: 1044
Created: October 1, 2019
Last Updated: June 26, 2024
Author: Laurie Sherrod

Online URL: https://hdkb.clemson.edu/phpkb/article.php?id=1044