Explanation
Placing emphasis
- Bold items on which you have specifically directed the audience to click, such as buttons, links, etc. if the name of the item is actually on the screen. When directing the audience to choose an item from a drop-down list, bold the name of the choice in your text.
- If a bolded word is followed by punctuation, do not bold the punctuation.
- Use regular quotation marks (") when referring to items with a long name on which the audience needs to click. Do not place them around technical terms that readers are likely to know, such as when referring to the Control Panel or Start button in Windows, referring to keys on a keyboard, or when referring to an icon. For instance, the phrase "click the pencil icon" would not be in bold and would not be in quotes.
- If you simply refer to the item but do not tell them to click it, use quotation marks around the name of the item. This also applies to instructing an audience to choose one particular item from a list, as in radio buttons or checkboxes.
EXAMPLE:
Locate the "Last Edited By" column.
- Italicize to stress words or phrases. Avoid using uppercase letters or bold to add emphasis.
- Use red text to emphasize extremely important information.
- Do not use both bold type and quotation marks simultaneously (unless you are quoting an item that appears in bold).
- Avoid bolding large sections of text.
- When listing various settings, bold the name of the setting and leave the setting itself un-bolded.
EXAMPLE:
Security type: WPA2-Enterprise
TIP, CAUTION, IMPORTANT, EXAMPLE, and NOTE
When you need to call special attention to a section of text, you can use either "TIP," "CAUTION", "IMPORTANT", "EXAMPLE", or "NOTE", depending on your needs. These are used to inform the audience of important information or special cases.
The text following the word "TIP", "CAUTION", "IMPORTANT", "EXAMPLE", or "NOTE" should not follow the same formatting of that first word. When applying the color formatting and bold, only select the word and the colon immediately following it. Apply the bold first, and then choose the color. Do not choose a color for "EXAMPLE"; it will default to black. For the others, use the colors shown below.
TIP
Color: #3598db
TIP: Tips are used to add information that may make the process easier or provide a shortcut for future troubleshooting.
CAUTION
Color: #e03e2d
CAUTION: Cautions are used to denote warnings that need to be acknowledged. Use these when the audience's data or information security is at stake, or proceeding may cause irreparable harm to hardware or software.
IMPORTANT
Color: #e67e23
IMPORTANT: Importants are used to add information that is less important than a caution but more important than a note.
EXAMPLE
Color: N/A
EXAMPLE: An example can be used to provide a lesson on what needs to be typed, or it can be an instance serving the purpose of illustration.
NOTE
Color: #2dc26b
NOTE: Notes should add an informative bit of information to an article that is an aside to the normal flow of the article. Use "Note" when "Tip", "Caution", "Important", or "Example" do not make sense.
Headings
- Use sentence case.
- Do not put colons at the end of the heading unless grammar absolutely requires it.
- Do not use bold for creating headings over sections. Instead, use the heading options (H4, H5, and H6) in the WYSIWYG editor. See the instructions directly below for the tool that you're using.
- "Heading 1" through "Heading 3" are reserved for the title of the web page, field names, and so forth. Do not use those headings. Start with "Heading 4". If you have two levels of headings, use "Heading 5" next. If you have three levels, use "Heading 6". If you need more than three levels of headings, consider finding an alternate way to present the content, such as breaking it up into multiple articles, using a table, or reorganizing the content.
In the top left of the WYSIWYG editor, click the drop-down menu and choose your desired heading option.
Keyboard instructions
- When asking the user to press a key combination on the keyboard, use a plus symbol (+) between the keys, with no spaces.
- Do not place the keyboard combination in bold.
- Keep in mind that macOS and Windows use different key combinations. For instance, Ctrl+C is the Copy command in Windows, whereas it is command+C on the Mac.
- Refer to keyboard keys using the exact wording on most keyboards. For instance, type "Ctrl" for PC keyboards and not "Control"; on Macs, it is "control" with a lowercase "c".
- Spell out punctuation instead of including it (for instance, Ctrl+comma).
GOOD EXAMPLE:
Ctrl+Shift+period
BAD EXAMPLES:
Ctrl + Shift + X
Control + Shift + ,
Dates
When a month and year are given, write out the name of the month and the four digits of the year (for example, January 2022). When a month, day, and year are given, use the standard US format (for example, January 1, 2022), and place a comma after the year if it's not at the end of a sentence. Use cardinal numbers instead of ordinals for the day (that is, "1" instead of "1st"). Do not add extraneous numbers (that is, do not write "January 01, 2022".) Always include the year, since doing otherwise may make the article incorrect if it is not updated before the next year rolls around.
Phone numbers
- For consistency, phone numbers should be written in the format 123-456-7890.
- When putting a telephone number into an article, please use the "tel:" protocol (similar to "mailto:") to create a link that will attempt to open the call in whichever telephone application the browser is configured to interact with. Highlight the number, choose the option to insert a link, and type the number prefaced with "tel:" into the URL box. Always specify the country code in the hyperlink (1 for USA), but not in the article text.
- Do not include the country code for any phone numbers unless international calling is involved or unless there are phone numbers in the same article that are for different countries. Otherwise, it is assumed that the country code is 1 for the United States.
- If there is an extension, put a comma and space, type the letters "ext" with a period and a space, followed by the extension number.
EXAMPLE:
806-742-1234, ext. 567
Lists
- Use to avoid long paragraphs. People are more likely to read a list than a dense paragraph.
- Lists are useful when your audience needs to type information in multiple fields on a single step.
- Do not use bullet lists for only one item.
Instructing the audience to type specific text
- If you instruct the audience to type specific text and the text is inline with your instructions, then put the text in bold.
EXAMPLE:
In the "Run" dialog box, type regedit and press Enter.
- Try to place the text on a separate line, if possible. You should especially do this in cases where the text is more than several words long. When doing so, follow the style guide in the section directly below titled "Error messages, terminal commands, email templates, and sample text".
EXAMPLE:
Type the following command and press Enter:
ipconfig /all
Error messages, terminal commands, email templates, and sample text
- Place in a separate paragraph
- Indent by 40 pixels (one click on the "Increase indent" button in the editor; see "Indentation" section below)
- Use the Courier New font
Indentation
- Left-align (that is, no indentation) all numbered steps (except for rare cases of sub-steps; see the "Numbered steps" section below for more on this).
- Indent screenshots and other images by 40 pixels from the descriptive text above it (one click on the "Increase indent" button in the editor).
Use the following buttons to increase and decrease indentation.
- While it is possible to get carried away, it is not unreasonable for an article to have three or four levels of indentation. If you get beyond two or three levels, it may be best to evaluate how to better organize your content making use of headings.
- Lists are indented automatically, but if you need to align them further to the right, then use the following code in the ul or ol tag: style="padding-left: 40px;". Increase the number by 40 pixels for each indent level needed.
- To indent an entire table, use the following code in the table tag: style="margin-left:40px;". Increase the number by 40 pixels for each indent level needed.
Numbered steps
- Do not use numbered steps if there is only one step.
- Begin with a number and closing parenthesis, followed by one space.
- Include at least one action for the audience to take.
GOOD EXAMPLE:
7) Type your eRaider username.
BAD EXAMPLE:
4. The "Set Password" screen will appear.
Two levels
Method A: Description of Method A
A1)
A2)
Method B: Description of Method B
B1)
B2)
Three levels
Method A: Description of Method A
A1)
A2)
a)
b)
Method B: Description of Method B
B1)
B2)
a)
b)
Four levels
Method A: Description of Method A
A1)
A2)
a)
b)
i)
ii)
Method B: Description of Method B
B1)
B2)
a)
b)
i)
ii)
Five levels
Method A: Description of Method A
A)
1)
2)
a)
b)
i)
ii)
Method B: Description of Method B
B)
1)
2)
a)
b)
i)
ii)
Indentation with embedded steps
TIP: Try to avoid having multiple levels of embedded steps, as it may be confusing for your audience to follow. Instead, consider reorganizing your content into multiple articles, using multiple sections with headings, etc.
Two levels
1)
2)
2a)
2b)
4)
5)
5a)
5b)
Three levels
1)
2)
Details for Step 2
2a)
2b)
a)
b)
2c)
3)
Anchors and "jump to" sections
For information regarding anchors and "jump to" sections, please view our article about this.
Tables
Please use a 1 pixel border for tables, a cellspacing setting of 0, and a cellpadding setting of 6.
Line breaks
If you need to prevent a line break from happening automatically between two words, use a non-breaking space. For more on non-breaking spaces, as well as more spelling guidelines, see Spelling and grammar guidelines for knowledge base articles and Texas Tech IT documentation.
1) On the WYSIWYG editor toolbar, click the "Special character" button.
2) Click the "no-break space" option. It is the seemingly empty box on the far top left-hand corner.
Microsoft settings shortcuts
- Microsoft has included an API that shortcuts to any feature in the Settings area in Windows 10. Any article that takes a user to the Settings area in Windows 10 should make use of this feature. A list of these shortcuts may be found on Microsoft's Windows Settings page at https://docs.microsoft.com/en-us/windows/uwp/launch-resume/launch-settings-app.
- Start with the text "One-click activation: Click the button below and click Open link. More instructions here, if necessary."
- Search for ms-settings in the knowledge base for examples of how this feature has been used in other articles before. Styling of the button should exactly match those examples.
- The code is as follows:
IMPORTANT: Copy the text below straight into the source code.
<p style="padding-left: 40px;"><a style="border: 2px solid transparent; outline: 0; color: #fff; background-color: #0067b8; padding: 5px;" href="ms-settings:remotedesktop">Enable Remote Desktop</a></p>
- The two main changes to this code will be toward the end. Change the text after the colon in "href=ms-settings:desiredsetting" to the corresponding setting for the article. Change the text at the end of the code, before the </a></p> tags, to name the button accordingly.
- Add ms-settings to the "Meta" field when using this feature in an article. This will allow your KB administrators to easily find articles later which have used this feature.
More resources
For more help, please see the following resources: