This article is for IT Solutions employees and outlines key guidelines for success in writing about technology and IT Solutions at Minnesota State University, Mankato.
Clarity and Audience Awareness
Be Clear and Direct
When writing about IT, keep your communication clear and straightforward. Avoid unnecessary complexity and focus on making technical details accessible to your audience.
Know Your Audience
Understand who you are writing for. Consider whether your audience is IT staff, faculty, staff, students, or service users (like those using TeamDynamix or Workday). Adjust your tone and level of detail accordingly.
Explain Why
Whenever possible, explain the reasons behind actions, especially for changes like service outages or new technologies. This helps your audience understand the benefits and importance of the updates.
Writing Style and Structure
Create Easy-to-Scan Content
Break up long paragraphs, use headings, bullet points, and clear formatting. This helps readers quickly find the information they need. Keep your messages concise and to the point.
Write Clear Subject Lines
For emails, the subject line should be specific and direct, and the key action or information should be indicated. It should use correct title case, meaning the first letter of each major word is capitalized and minor words are not.
Examples:
- Correct: Service Alert: Update to Workday
- Incorrect: Workday Is Getting An Important Update This Weekend
Use Active Language Over Passive
Use active language to make your writing more engaging and direct. Active sentences are clearer and more concise, helping your audience understand your message quickly.
Examples:
- Correct: IT Solutions will install the system.
- Incorrect: The system will be installed by IT Solutions.
Proofread Your Content
Ensure your content is free from errors. Use spelling and grammar tools, like spell check, and have a colleague review your work before it’s published.
Punctuation
Commas and periods go inside quotation marks, in the standard American style, despite it being inconsistent with the way things are done in code, and inconsistent with the standard British style, as noted in the Google Developer Documentation Style Guide.
Examples:
- Correct: The error message says, “Access denied."
- Incorrect: The error message says, "Access denied".
Language and Terminology
Avoid Jargon
Unless writing for IT professionals, minimize the use of jargon and explain terms when necessary. Be attentive to language that has a specific meaning for IT people and an entirely different meaning for non-IT people, such as audit, client, domain, machine, package, tenant, and many others. Additionally, many technical terms, such as endpoints, SSID, and others, are not familiar to a non-technical audience; use other terms or define the terms you’re using, when applicable.
Simplify IT Terminology
Use clear terms that are universally understood. For example, instead of abbreviating system names or departments, write them out in full.
Examples:
- Correct: IT Solutions Center
- Incorrect: ITSC
Using Acronyms
Avoid overusing acronyms. Acronyms are acceptable on second and subsequent references; place the acronym in parentheses on the first reference.
Examples:
- Correct: IT Solutions (ITS) recently upgraded this service.
- Incorrect: ITS recently upgraded this service.
Formatting and Accessibility
Links
- Format links by highlighting the text and inserting the link.
- Do not display URLs (example: https://services.mnsu.edu/TDClient/30/Portal/KB/?CategoryID=117).
- Insert the link directly into the text.
- For accessibility, use clear and descriptive link text. Avoid phrases like “click here.” This helps users with screen readers understand where a link will take them.
- Ensure buttons and links are navigable using a keyboard and have visible focus indicators to show where a user is on the page.
Examples:
CamelCase
Use of CamelCase has been decided by University Marketing as the consistent and accessible way to use naming conventions. This means no space been words when used in a name and the first letter of each word must be capitalized with all other letters lowercase.
Examples:
- Correct: MavMail, MavLife, MavLabs
- Incorrect: MavMAIL, Mav Life, MavLABS
Dates
Write out the full name of the day (e.g., Tuesday) and the full name of the month (e.g., September). Use numerals for the day and year. Do not use ordinal suffixes like “th” (e.g., write September 12, not September 12th).
Examples: Tuesday, September 12, 2025; September 2025; September 12
Times
Use numerals for times and lowercase “a.m.” and “p.m.” with periods. Use a colon to separate hours from minutes (e.g., 9:30 a.m., 2:45 p.m.). Omit “:00” for times on the hour (e.g., 3 p.m.). Use “noon” and “midnight” instead of 12 p.m. and 12 a.m.
Examples: 9:15 a.m., 3 p.m., noon, midnight