This style guide is a living document to help us keep the Tech website clearly written and consistently edited.
The Chicago Manual of Style is the basis for this, along with some highlights from Mother Jones. Both of these sources are brilliant and well-thought-out; they do the debating about these conventions so we can get on with saving the world, one Zoom tutorial at a time.
Capitalization
Capitalize My Title will take care of it for you!
- Use title case, not sentence case, for article titles (E.Flo Clinical Events, not E.Flo clinical events).
- For blog articles, use sentence case, because they are longer and chattier (and sometimes are, actually sentences).
- Only use the name of the app as the landing page. Page titles should be specific, not just the app name, so that the app name can be used as the landing page in the URL. If it’s an intro article, call it [App Name] Basics.
- Capitalize idioms like “Log In to Your Account”—the preposition is part of the meaning.
- Spell out acronyms on first use—we all have different backgrounds and may not always be familiar. Put the acronym in parentheses if it’s mentioned again later in the article.
- Plural acronyms take a lowercase s, no apostrophe.
- See also: Icons, use of.
- For acronyms that are the names of companies, we turn to Mother Jones:
Do not SHOUT IN ALL CAPS for companies or brands unless they’re actual acronyms. We’re not their megaphones. Examples: Fox (not FOX), Politico (not POLITICO), Facebook (not FACEBOOK), but C-SPAN is all caps because it’s Cable-Satellite Public Affairs Network. We got you, C-SPAN. In all other cases, stay true to name for accuracy, such as eBay, YouTube, ThinkProgress, BuzzFeed News. (This is called CamelCase capitalization.) Ebay when starting a sentence.
Code, Frequently Used
- Color: span style=”color:blue”
Dates
- Always spell out: Month day, year.
- If it’s just Month year, no comma is needed: May 2058.
- Never, ever use slashes in dates, like 5/29/2004.
Icons, Use of
- [name] [label: icon, button, feature, etc.] actual icon, if there is one.
Example: Magnifying glass [name] icon [label] [icon from Font Awesome] - To include the icon in the Documentation Action style, put inside the /span
- If no icon available, Doc Action the words only. Capitalize the first word.
Image Organization and Naming Conventions
- Media file organization is by page, under parent page. Save in SharePoint Website Assets Folder as well.
- Asset titles: page name_asset name_year
- JPG or GIF: 800px or 500px width (do not upload PNGs—convert to Web JPGs)
- Link to media file for each image so it is clickable/enlargeable.
- Add Alt Text: [page name]-[asset name or what’s being shown]-[type of asset (image, gif)]. Use hyphens between words.
- Videos should be uploaded to YouTube.
Italics
- Don’t put running text in italics for more than one paragraph—two max—if using as an intro.
Page Title Conventions + URLs
- Only use the name of the app as the landing page. Page titles should be specific, not just the app name, so that the app name can be used as the landing page in the URL. If it’s an intro article, call it [App Name] Basics.
Punctuation
- Don’t use ampersands—spell them out. (The only exception I can think of to this is in one term: Q&A.)
- Don’t use a colon at the end of a heading. (It’s unnecessary on a page with proper text formatting like ours.)
- Capitalize the first word after a colon if it’s the beginning of a new sentence.
- Capitalize the first word following a colon in a headline.
- Use a serial comma, because it’s what civilized, detail-oriented people do.
- If using an em dash (—), use it without spaces. Do not use spaces on either side of a hyphen (-) in these instances. To insert an em dash, press Shift+Option+dash (-).
- Use an en dash (–) for number ranges (for example, 83–100) or compound adjectives (New York–bound train).
- Space ’em out—it just looks so much better: . . . Use a non-breaking space, and we’ll all be happy.
- Adverbs that end in -ly are never hyphenated.
- Hyphenate “well-” compounds before a noun, but not after: A well-read student / he is well read.
- Add periods at the end of captions.
- Don’t use double spaces after a period, because we’re in the New Millennium.
Numbers
- Spell out round numbers.
- Use numerals for lists of numbers.
- If the number is the first word in a sentence, spell it out. (Or reword the sentence!)
Specific Terms
- Apple Pencil
- double-click, not doubleclick (and think about if it should be ‘tap’ if it’s iPad-centric!)
- E.Flo MD (capital E, period, no space, capital F, no period)
- login (noun) vs. log in (verb)
- note-taking
- Setup (noun) vs set up (verb)
- Sidebar menu (capped Sidebar only)
- Whiteboarding
- Wi-Fi, not WiFi or wifi
- Your (capitalize in headings)
- Use College of Medicine, not ESFCOM
Text Formatting
- H1=title
- H2=subtitle
- H3=A head
- H4=B head
- H5=C head
Note that H3–H5 will get pulled into the Table of Contents query, so be aware that you can’t just use that style for text formatting. If you want a line to look like an H3/4/5 but not be pulled in to the TOC, set it as a p and then style it manually.
Another note: When a B-head directly follows an A-head, use a heading widget for H3 and a text editor widget for the H4
The Documentation Action style is used to indicate something that should be clicked or typed or found on a page. (Verbs really aren’t necessary to be set as DAs.) These are the kind of terms that you might think to put into quotation marks, or in bold or italics. No need to wonder—just use the Doc Action, and it’ll be effortless formatted correctly . . . and when we decide to change our colors, it’ll be updated automatically.
Note that this has nuance to it! We can do hard things.
- Indent lists (bulleted or numbered) when they come under an intro line of text. (If they come under a header, like this paragraph, no indent is needed.)
Please Do Not
- Do not underline any text (it looks like a link!).
- Do not center text, unless it’s the article title (and so set up in the template) or you have a very good reason to do so. If you really do need to center it, the text should be very, very short.
- Do not tweak text styles—use what is built into the template/style sheets.
- Do not run an alert box at the start of an article.
But wait: there's more!
Check out the Style Guide, in case you need more extremely specific guidelines.
by the Office of Technology