Overview

Documentation is more effective if all documents share a unified look, feel, and tone. Be consistent when using bold and italic text, header sizes, figure markers and image size and alignment.  

Introduction

Use an "Overview" header for documents that have a sequence of steps. Otherwise, use an "Introduction" section (such as this) describing the document.

For Introduction/Overview paragraphs, the first paragraph is the actual introduction or overview and the second paragraph is a further explanation related to exceptions.  

A document with steps always gives a quick glance at what is needed. This comes immediately before the first step. If there is additional text, put it before this sentence. Consider the following example:

You need the following information to set up Exchange email on your iPhone:

• Username: your NetID
• Password: your NetID password
• Email Address: yourNetID@email.tamu.edu

These bulleted list components are ordered based on the order of what appears on the screen. Also, use the built-in bulleted formatting whenever possible. It creates a nice consistent indentation format that makes reading easier. Generally, you will know to use this format when the sentence ends with “:”. Numbered instructions should also use the built-in numbering format tool. Should you need to nest within a numbered or bulleted section (see the following example), you will use the indention buttons (). The subsection label (number, bullets, etc.) cannot be changed from the default.

1. Test
   1. Test Subsection

Table of Contents

In a document with more than 2 sections, a table of contents needs to be added. It should be placed after the Introduction/Overview section. All headings are to be added, including second or third headings: 

• Heading 1
  • Heading 2
    • Heading 3

Add internal anchors to the table of contents and the corresponding section in the document (http://help.typepad.com/anchor-tags.html).

Part 1: Contents

Do not type a title for your page into the "Text" box. The page title will be automatically added at the top of the page by ServiceNow (provided that the "Knowledge Base" type has been switched to "TAMU"). Adding a title will result in the title being listed twice, which is redundant. 

Use periods in sentences, except in bulleted lists, headings, and figure descriptions beneath images. 

Always write instructions as follows: “In the "Password" field enter your NetID password”, not “Enter your NetID password in the "Password" field”. 

Everything should be written in the present, active tense. Ponder the following example:

“This is”, not “this will be”, “this should be”, etc.

If the document is talking about an iPhone, continuously reference “iPhone”, not “device”, or “phone”, etc. throughout the document. Be specific.

“Login” is a noun, “log in” is a verb, “setup” is a noun, “set up” is a verb.

Always use “username”, not “user name”.

Do not use the word "please" unless you are directing the customer to do something that will greatly inconvenience them (if in doubt, don't use it). 

When talking about errors, refer to them simply as "errors", not "error messages". 

(source: Microsoft Manual of Style)

Part 2: Headings

There are no default heading sizes in the TDNext Knowledge Base. The text is bold and the sizing is as follows: 

Heading 1

Heading 2

Heading 3

In general, the one you will use the most is Heading 2. Heading 1 is already in use for the automatically generated page title. Use Heading 2 to begin major sections of the document you are writing. If you have sub-sections, use Heading 3. Headings 4-6 should not be used. The section names in this document are size Heading 2. For example, consider the following:

Advanced Setup

The advanced setup provides further explanation for users.

Step 1: Installing

1. Click the Install icon
2. Click Ok

Step 2: Connecting

1. Enter your system information
2. Choose to run at every login

Step 3: Running

1. Set your location so every time you run the program it automatically connects
2. Click Finish

Part 3: Bold and Italic Text

Our style for bold and italic text is this: If you click it, tap it or select it, then it should be in bold. If you type it in, it should be in italics. For example:

Tap the Settings app and type your NetID as the user name.

Always use “your NetID”, not “NetID”, or “your Net ID”, etc.

Always use “your NetID password”.

NOTE: Use italics when shifting the reader's context. In other words, don't italicize the phrase "your NetID" if you want to refer to a generic reader's NetID (in a sentence, for example). Do italicize the phrase if you are using it as a placeholder for something you expect the reader to type (in a list of settings to insert into fields).

For quoted fields, quote it once, and then for any following reference, just make it capitalized. This way the quotes don't become distracting.

Part 4: Images

One of the most inconsistent portions of our documentation, historically, has been our formatting and handling of images. This part of the document will give examples of both incorrect and correct image sizes (to illustrate why we use the sizes we do) as well as how we align those images and how we use figure markers.

1. All numbered steps are in this exact format. Wide images can often be too wide to appear comfortably on a screen. Place pictures on the next line immediately below the step they are illustrating. Each step that would benefit from illustration should get an image associated with it. A step is defined by a screen change (hence the need for a new screenshot). Otherwise, group multiple instructions from one screen in one step.
2. 
3. Leave an extra line of space between each step in the process. A step has no space between it and its following picture. A picture has a space between it and the next step. 
4. Limit width to no more than 650 pixels.
5. NOTE: When preparing your images, Size them appropriately before you upload them. "Resizing" them in the article does not resize the actual picture, but merely its displayed size. A 4000x4000 JPG that's 5MB in size that has been "resized" in the article to 400x400 will still require the customer to download 5MB of file. Don't do that.
6. NOTE: The "note" portion should be merely bold, not a heading. Also, "notes" are only referenced as Note, as opposed to ***Note, Important Note, etc. This helps preserve formatting.
7. Even if a picture meets the 650 pixel maximum width, its height can be such that it is inappropriate for our documentation.
8. 
9. 
10. As you can see, that picture is just too big to be practical. As a result, please resize excessively tall pictures to about 500 pixels in height.
11. If there are duplicate steps in a document, do not duplicate the images associated with them. In other words, no single image should appear more than once in the document. If a step calls for a previous image, simply provide a reference to it without attaching said image.
12. Always end a sentence, THEN type click next as a new sentence. Consider the following example:
13. In the "Password" field enter your NetID password. Click Next.
14. The final (completion) instruction requires its own number step AND its own screenshot.
15. All phone numbers are in the following format: “(979) 845-8300”, not “979.845.8300”, “979-845-8300”, etc. This is in accordance with the Microsoft Manual of Style.
16. All documents end with the text: “If you have any further questions, email helpdesk@tamu.edu or call us at (979) 845-8300.”