Writing Style

Voice and tone

Voice stays consistent, but tone changes depending on the situation and audience. Our voice is what makes ITS sound like ITS across all our communications. We want to keep our ITS voice consistent but change our tone as needed.

The ITS voice is

• straightforward and clear. We prioritize clarity and reader comprehension over flowery language or convoluted sentences.
• upbeat. Use positive, rather than negative language, when possible. We want users to focus on the ways that ITS enables University excellence and have them feel empowered and that their problems are met with solutions.
• respectful. Technology topics can be complex, and the UNC community encompasses people with varying degrees of comfort with technology and numerous languages, learning styles and abilities. We are translators and our best writing is when we connect with our users.
• professional. We’re IT experts and we want our writing to inspire trust by exuding confidence and competence.
• customer-focused. Focus on the user point of view. Think about the problems they are trying to solve, the questions they may have, or why they might be interested.

Tone

Tone generally refers to how a user feels when they read something. For most instances, our tone is friendly but still professional. This means:

• be direct. Get to the point of the piece quickly, without giving long explanations, going on tangents or discussing edge cases.
• write for action. A lot of our content is oriented around actions like finding, changing, solving or doing. Center your writing around the action to be done.
• write simply. Remove barriers that might make it hard for people to understand your writing. Avoid unnecessary modifiers, use simple words and short sentences. Use specific language, limit acronyms, jargon and colloquialisms.
• write conversationally as if you were speaking directly to a customer. Be friendly and personable, not pretentious or stuffy. Writing conversationally improves reading comprehension and makes ITS feel approachable and caring.
• use active voice instead of passive voice. This helps with clarity but also emphasizes an action-oriented professional approach.

For specific audiences, the tone may be a little different. In all communications, we still follow the University identity guidelines and AP style.

Formal tone

• All-campus emails, policy, announcements.
• Limit contractions, no exclamation marks, no parentheticals, no humor.

Professional tone

• Knowledge base articles, ITS website content, ITS News articles, releases to other campus newsletters/communications.
• Use contractions, limit exclamation marks, limited parentheticals and very mild humor acceptable.
• Professional tone is our default formality level.

Casual tone

• Social media, student-only communications, internal ITS communications.
• Exclamation marks (no more than one at a time), parentheticals and mild humor are acceptable. A more fun/casual tone is expected.

These three tone levels match the formality levels in Microsoft Word’s Editor tool. Set Editor to your desired formality level for automated guidance while you’re writing.

Examples

Creating content for knowledge articles

Help articles should focus on content that is specific to UNC and geared to UNC users.

• Where appropriate, use and link to external websites and resources that offer more general information on a topic.
• Do not duplicate content that exists on company/provider sites, as we can trust that companies will keep their documentation up to date more easily than we can.
• Do not copy content from external websites. If you need to adapt existing content to fit UNC specifics, rewrite the content. If it needs minimal rewrites, link instead.

Types of knowledge articles

Technical content articles vary in target audience, goal and tone. Technical content is built from five templates, which serve different purposes and readers.

FAQ  (frequently asked questions): Use FAQs sparingly. They are often not a good format for sharing information. Read: No More FAQs before you create one.
Overview: Overview or table of contents for large topics (e.g., Microsoft 365).
How To: Step-by-step instructions (e.g., set up Wi-Fi).
Informational: This is what this service does (e.g., PSK).
Referral/Informational: Short blurb that explains the service and then links to the service (e.g., go.unc.edu).

Writing with the user in mind

Someone reading technical content is usually looking to answer a specific question. That question might be broad or narrowly focused, but our goal is to provide answers without distraction.

For each document, consider your audience’s background, goal and current mood. Ask these questions:

• What is the experience level of the reader? Does the reader have a base knowledge or advanced knowledge about this topic?
• What is the goal of the reader? To complete a task? To research a topic?
• Is the reader in the middle of a task? Are they in a hurry? Could they be frustrated?

When relevant, prime the reader with a brief outline of an article’s focus in an introductory paragraph or section, and stick to the topic at hand. Keep sentences, paragraphs and procedural steps focused and concise.

Tips for writing technical content

Start with the title

Your title should be the anchor for your content. Writing a clear title will help you clarify the goal of the piece and how much content it contains.

Write a title that:

• Explains what content a user should expect. E.g., “Enroll in Duo 2-Step Verification.”
• Use verbs for how-to articles to differentiate from “about” articles. E.g., “Enroll in Duo 2-Step Verification” vs. “Duo 2-Step Verification.”
• Is based on terms a user might search for. E.g., use terms like “Wi-Fi” or “eduroam” instead of “wireless.”

Stay relevant to the title

When a user clicks the title of an article, the user expects the content to be related to the title. Don’t stray too far from the title or topic at hand. Use links to make related content available. If you find you’re getting too far from the intended topic, then you may need to create a separate article. If you must include edge cases or tangentially related information, set it aside in a ‘Before you start’ list or ‘Notes’ field.

Keep headings and paragraphs short and scannable

Focused users often scan an article for the part that will answer their particular question. To facilitate scanning, make headings short, descriptive and parallel.

Use lists and bullet points

Keep paragraphs short by breaking step-by-step instructions into numbered lists and digestible snippets into bullet points.

• Separate steps into logical chunks, with no more than two actions per step.
• Use parallel sentence or phrase construction on each item.
• End bullet or list items with a period, even when the item is not a complete sentence.

Use second person and describe actions to a user

Technical content talks to users when support agents can’t. Use “you” or implied second person when writing content (e.g., “log in to your account,” instead of “one logs in to one’s account”).

Strive for simplicity and clarity

Be as clear as possible. Use simple words and phrases, avoid hard-to-translate idioms or words, focus on the specific task and limit the number of sentences per paragraph.

• Cut or tighten redundancies, gerunds, adverbs and passive constructions.
• Use the simplest word (e.g., “setting” vs. “configuration”).
• Limit paragraphs to three sentences.
• Use specific, active verbs for tasks.

Show context through embedded screenshots and GIFs

Screenshots and GIFs may not be necessary for every article or process but can be helpful to orient new users.

• Focus attention by cropping screenshots tightly around the action.
• Annotate images to add clarity when needed and limit annotations to boxes, circles, arrows or a word or two.
• Make sure gifs do not flash or blink excessively, see WCAG guidelines.
• Add quality alt text, not things like “screenshot” or “interface.”
• Do not rely solely on screenshots or gifs; include all instructions in written form.

ITS and campus-specific terms

ITS terms

• ITS Service Desk, not Help Desk
• ITS Manning, ITS Franklin, no hyphens
• Frank Porter Graham Student Union on first reference, Student Union on second
• ConnectCarolina  
• Carolina Computing Initiative on first reference, CCI on second
• 2-Step Verification 
• ServiceNow
• Microsoft 365 (The brand is no longer Office 365.)
• eduroam (always a lowercase “e” unless at the beginning of a sentence)
• enable vs. allow; ITS primarily enables work or learning instead of allowing it

ITS divisions, units and groups

• Refer to ITS as a department. Within the department, ITS has nine divisions. For entities within the divisions, refer to them as units or groups.
• We use ampersands in division and unit names.
• When referring to the division for a campus audience, on first reference include ITS at the beginning (e.g., ITS Customer Experience & Engagement, ITS EdTech) without hyphens.
  • Exceptions: Digital Accessibility Office and Information Security Office. These groups are housed within ITS but have a larger campus mandate.

Units and groups and their abbreviations

• Office of the CIO
  • Project Portfolio & Change Management (PPCM)
  • Policy Office
• Customer Experience & Engagement (CE&E)
  • Computer Repair Center (CRC)
  • Carolina Computing Initiative (CCI)
  • Managed Desktop Services (MDS)
  • University Administration Support (UAS)
  • Digital Accessibility Office (DAO)
  • Digital Services
  • Digital Communications
  • ServiceNow Engagement Team
  • ResNET
  • Service Desk
  • Business Systems Help Desk (BSHD)
  • Voice Services
• Data & Reporting Environments & Application Middleware (DREAM)
  • Enterprise Database Administration (DBA)
  • Enterprise Reporting & Departmental Systems (ERDS)
  • Middleware
• Educational Technologies (EdTech)
  • Classroom Support & Learning Space Design (Classroom Hotline)
  • Educational Technologies Systems & Services
• Enterprise Applications (EA)
• Finance & Administration (F&A)
  • Software Distribution
  • Human Resources & Administration
• Infrastructure & Operations (I&O)
  • Enterprise Operations
  • Global Systems
  • Networking
  • Operations Center
  • IT Service Management (ITSM)
• Research Computing (RC)
  • Research Engagement & User Support
  • Research Database Support
  • Infrastructure
• Security & Identity Management
  • Information Security Office (ISO)
  • Identity & Access Management (IAM)

Campus-specific terms

• One Card, two words
• Onyen, not all caps
• Spring, Fall, capitalize semesters
• UNC-Chapel Hill, instead of simply UNC at first reference. Never use UNC-CH.
• University, capitalize even when standing alone, when referring to UNC-Chapel Hill.
• master’s degree , bachelor’s degree. MFA, BFA, MSc, etc. are allowed but not preferred.
• Capitalize a department’s formal name (Department of Physics) and shortened version (Physics), do not capitalize a field of study.
• Don’t capitalize names of majors unless the major itself is a proper noun (English) .

AP style grammar and mechanics

• Avoid serial commas. If the list is unclear without a serial comma, rewrite the list so it is clear.
• Periods and commas go within quotation marks.
• Periods go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.
• Use exclamation points sparingly, never more than one at a time.
• One space after a period and colon.
• For long names and acronyms that are not common, write out the entire name on first reference and add a parenthetical with the acronym. On subsequent references, you can use the acronym. (e.g., Network Operations Center (NOC))
• For common acronyms, you can use the acronym on first reference. Examples of common acronyms include CSS, HTML, URL, API or NASA.
• Generally, omit periods in acronyms.
• No apostrophe when making figures and letters plural.
• Capitalize individual job titles for specific roles, don’t when referring to roles in general terms.
• No -th, -rd, -st after dates, just the number.
• Dates need a comma between the day and the year as well as after the year in a sentence.
• Spell out the day of the week and the month (note: this is a slight divergence from AP style).
• Use symbol % for percent instead of spelling out.
• No middle initial unless there’s a need to clarify.
• Phone numbers use dashes without spaces between numbers.
• Numbers one through nine spelled out, numerals for 10 and above.
• For figures greater than 999,999, use million or billion (2.8 million, 6 billion).
• Use a comma in a figure greater than 1,000, unless it’s a date.
• a.m. and p.m. with a space after the number.
• No minutes for on-the-hour time (8 a.m. and 8:30 p.m.).
• noon, not 12 p.m. or 12 noon.
• “who” for people, “that” for inanimate objects.
• Refer to a company, department or product as singular; use “it” instead of “they.”
• OK, not ok.
• toward, not towards.
• Photo captions don’t use periods.
• Use sentence case for headings (not Use Sentence Case for Headings).
• Use e.g. not ex. for examples. When using e.g., a comma follows the second period. (e.g., this example)
• Do not italicize email or web addresses. Use normal font. Include text only (the actual address should be embedded in the text link itself).

Accessibility quick tips

• Use Web Carolina Blue hex code #007fae for link.
• Use alt text on all images that are not solely decorative. For examples, view guidance from WebAIM.
• Use descriptive links; avoid “click here” or “learn more.”
• Headers should be nested and consecutive. Don’t skip a header level for styling reasons. Page title is H1, top-level sections are H2s, subsequent are H3 and beyond.

Tech glossary

• 8x, 16x Format for values that denote the speed of drives such as CD and DVD drives
• access point Abbreviate as AP. Plural, APs. Wireless access point (WAP) is redundant because AP is assumed to be part of a wireless network
• back up (v.), backup (n. or adj.)
• bandwidth, broadband
• bps bits per second. No space between number and bps (800bps)
• CAPTCHA
• CD-ROM
• cookie
• cyber Generally, one word for this prefix plus root words; but hyphenate if root word starts with capital letter (cyberattack, cybercrime, cyber-CIA)
• disc, disk Computer hard disk, disc for CDs, DVDs and laser discs
• dot-com
• download
• dpi Space between numeral and abbreviation (300 dpi)
• e-book
• email (singular and plural)
• Ethernet, always capitalized
• firewall
• flow chart (n.), flow-chart (adj.)
• GB gigabyte. No space between number and GB (1GB)
• Gbps gigabits per second. Note the lowercase b, which distinguishes this from GBps, a different measurement. No space between number and Gbps (1Gbps)
• GBps gigabytes per second. Note the uppercase B, which distinguishes this from Gbps, a different measurement. No space between number and abbreviation (1GBps)
• GHz gigahertz. No space between number and GHz (5GHz)
• hard drive
• homepage
• HTML
• internet, always lowercase
• KB kilobyte. No space between number and KB (1KB)
• Kbps kilobits per second. Lowercase b distinguishes this from KBps, a different measurement. No space between number and Kbps (300Kbps)
• KBps kilobytes per second. Uppercase B distinguishes this from Kbps, a different measurement. No space between number and KBps (1KBps)
• keyboard
• kHz kilohertz. No space between number and kHz (1kHz)
• life cycle
• listserv
• log in (v.); log in to (v.); login (n.), not log on; logout (n., adj.); log out (v.), not log off
• lookup (n.)
• MB megabyte. No space between number and MB (1MB)
• Mbps megabits per second. Lowercase b distinguishes this from MBps, a different measurement. No space between number and Mbps (1Mbps)
• MBps megabytes per second. Uppercase B distinguishes this from Mbps, a different measurement. No space between number and MBps (1MBps)
• memory, diskspace
• metadata (n.)
• metatag (n.)
• MHz megahertz. No space between number and MHz (1MHz)
• multifactor not multi factor
• offline
• offscreen
• open source (n.), open-source (adj.)
• opt-in (n., adj.), opt in (v.)
• pop-up
• plug-in (n., adj.), plug in (v.)
• RSS, abbreviate for Really Simple Syndication
• restart, not reboot
• screencast, screenshot
• sign-in (n., adj.), sign in (v.), sign in to (v.)
• sign-out (n., adj.), sign out (v.), sign out of (v.)
• sign-up (n., adj.), sign up (v.)
• site map
• smartphone
• spam
• TB terabyte. No space between number and TB (1TB)
• upload
• URL
• userfield
• username
• videoconference, videoconferencing
• virtual private network on first reference, VPN on second
• virus, spyware, trojan, worm, malware
• voice mail, voice mail box
• web
• webcam
• webcast
• web page
• website
• Wi-Fi
• wiki
• workflow