Purpose
The purpose of the technical writing style guide is to
- Increase understanding and avoid confusion for users
- Create a polished, professional product
- Provide a consistent style and experience for all OTDI technical writing, such as training, how-to documentation for tool use, and step-by-step instructions on websites and in emails
These standards are to be used in addition to Ohio State editorial style guidelines, which are based on Associated Press style (AP style). You can search Ohio State’s customized AP Stylebook online for quick reference.
These standards are not a substitute for professional judgement. There may be times when you need to not follow the standards, but they should be rare.
Tone
In general, tone should be conversational and friendly without being too informal. Language should be simple and clear.
- Keep the writing personal. Talk to the reader directly by using “you” and “your” (second-person).
| Preferred | avoid |
|---|---|
| You are responsible for providing your information. | Users are responsible for providing their information. |
- Keep your writing focused on the customer. Consider your audience when choosing word, format, and examples.
- Write to approximately the eighth grade level. Use a combination of simple and compound sentences, averaging 15 to 20 words maximum per sentence.
- Be concise and consistent. Use the same word to mean the same thing every time. Use similar styles and formatting to present similar information.
- Use authoritative words. Use tentative words such as “may,” “might”, “can” “should,” and “seem” only when absolutely necessary.
- Avoid technical or business jargon, gender-specific language, slang, “please,” and “simple” or “easy.”
- Write in a direct, unambiguous and active style; avoid passive voice.
| Preferred | Avoid |
|---|---|
| The team will review the form. | The form will be reviewed. |
| Supervisors make changes. | Changes are made by supervisors. |
- Use positive language and examples, not negative ones.
| Preferred | Avoid |
|---|---|
| Fill out all fields. | Don’t forget to fill out every field. |
| Before you start, have all your documentation prepared. | Don’t forget to have all of your documentation prepared before you start. |
Grammar, Formatting, Punctuation, and Word Use
Use commonly used words and one-syllable words over multisyllabic words.
| preferred | avoid |
|---|---|
| Use | Utilize; leverage |
| Write | Compose |
| Get | Obtain |
| Buy | Purchase |
Acronyms
Avoid acronyms and abbreviations wherever possible. Spell out acronyms on first use, including the acronym in parentheses immediately after. In some cases, acronyms or abbreviations are common and understood by the audience and are therefore OK to use. Ohio State’s customized AP Stylebook offers guidelines on which acronyms are generally recognized and acceptable to use on first reference.
| preferred | avoid |
|---|---|
| All digital information must comply with Minimum Digital Accessibility Standards (MDAS). | All digital information must comply with MDAS. |
| Use HTML to format the information. | Use Hypertext Mark-up Language (HTML) to format the information. |
| Include all degrees, such as PhDs | Include all degrees, such as Doctors of Philosophy (PhDs) |
Bold
Use bold type to refer to a specific item or section of a page.
| Preferred | avoid |
|---|---|
| Click or tap the Activate Now button. | Click or tap “Activate Now.” |
| Access your course from the My Courses widget. | Access your course from the “My Courses” widget. |
Check
When referring to a check box, use “check.”
| Preferred | avoid |
|---|---|
| Check your pronoun preference. | Select your pronoun preference. |
Citations
Use American Psychological Association (APA) style(link is external) for citations, if needed.
Click, Tap and Press
Use “click” for buttons, icons, links and tabs for applications that are primarily used on computers. Use “tap” for buttons, icons, links and tabs for applications that are primarily used on mobile devices. Neither would should be followed with “on.”
When referring to a keyboard key, use “press;” do not follow with “on.”
| Preferred | Avoid |
|---|---|
| Click the print icon. | Click on the print icon. |
| Tap the share icon. | Tap on the share icon. |
| Press F1 to put the display to sleep. | Press on F1 to put the display to sleep. |
Capitalization
| Capitalize | do not capitalize |
|---|---|
| The first word of a sentence | Technical terms |
| The first word of a bulleted item in a list | Common terms |
| Proper nouns | Email addresses |
| The first letter of every word in titles and subtitles – except articles, prepositions, and conjunctions | Web addresses |
Commas
Use a comma after the final item in a series before the conjunction. This comma is known as a serial comma or Oxford comma. While generally not used when writing in AP Style, serial commas are useful for clarity and therefore are recommended for technical writing.
| Preferred | avoid |
|---|---|
| Type your name, department, and phone number. | Type your name, department and phone number. |
Commas always go inside quotation marks. For additional comma guidelines, see the AP Stylebook.
Decisions
Rather than trying to identify optional and required steps or actions, write procedures that include all necessary steps. Use “if applicable” if the information may or may not relate to the situation. Use “if available” if the information is not required but may be available at the time the information is added.
| Examples |
|---|
| Check Age 18 or Older, if applicable. |
| Select the Marital Status, if available. |
Examples
Use “including” or “such as” instead of “etc.,” et al.,” or “e.g.”
| preferred | avoid |
|---|---|
| Include all information, such as name and birthdate. | Include all information (e.g. name, birthdate) |
| You should review all materials, including job aids, websites, and your notes. | You should review all the materials, job aids, websites, your notes, etc. |
| You will have documents such as manuals, job aids, and checklists to help you complete your work. | You will have documents (manuals, job aids, checklists, etc.) to help you complete your work. |
Faculty
When referring to those who teach classes at the university, “instructors” is preferred, since not all instructors are faculty members. “Faculty and staff” is acceptable if you are referring to employees of the university.
Lists
Use bulleted or numbered lists where appropriate. Numbered lists should be used only if the order of the items is important.
Use parallel construction in list items; for example, start all items in the list with a noun or start all items in a list with a verb.
Avoid lists with only a single item, periods at the ends of list items, and full sentences as list items.
Punctuation
Exclamation points should be used rarely, if at all.
Period and commas always go inside quotation marks. Dashes, semicolons, colons, question marks and exclamation points go inside quotation marks when they apply to the quoted matter and go outside quotation marks when they apply to the entire sentence.
With the exception of serial commas (Oxford commas), use the AP Stylebook as your guide for punctuation use.
Select
When referring to a radio button or dropdown menu, use “select.”
| Preferred | avoid |
|---|---|
| Select the delivery location. | Check the delivery location. |
The Ohio State University
Use “The Ohio State University” on first reference. For subsequent references, use “Ohio State,” “the university,” or “university.” Do not capitalize “university” when used alone.
For additional guidelines, visit the university’s brand website.
Type
When the user will be typing in a field, use the word “type.”
| preferred | avoid |
|---|---|
| Type the employee’s full name. | Enter the employee’s full name. |