General Style, Subject Reference, and Voice Notes
Focus on the user experience, the call to action, and their journey from action to results.
Refer to City in first person plural (we/us); the community in second person singular (you).
Use active voice (“we will grant” vs “it will be granted”) with an open, aspirational tone.
Avoid use of “citizens;” try “community members” or “residents and businesses”.
Focus on personhood (“people with a disability”) rather than their activity (“disabled”).
Avoid gendered language.
Editorial Best Practices
Give the user results that are limited and not ambivalent. Multiple search results with similar content are difficult to understand.
Consolidating information into less content improves the search experience.
Make your pages longer with headings to separate sections. Use the Heading 2 format and the "Table of Contents" feature that creates an "On this page" menu for easy pages with lots of information on a subject.
Refrain from duplicating information across a service and its guide. Try to deliver a service that explains itself. If the application is hard to understand, consider updating the application rather that writing long guides to using the application.
When To Use Images
"Communicate, don't decorate."
— unknown source (but popular in user experience communities)
Use photography and graphics sparingly—and only when they help communicate information to the user.
Use photography to draw the eye to featured content or the next most important related content to the current page.
Events Are Content for a Specific Date and Time
Use events for content that will progress from being "upcoming" to "recent" to a searchable archive.
Events work well for meeting announcements with agendas. The meeting can then be updated with the meeting minutes and presentations from the meeting. This makes it an automatic archive of important advisory group content.
Limit Use of the Frequently Asked Question (FAQ) Format
While there is some debate among usability experts about the use of a question/answer format, experts largely agree that FAQs are easily misconstructed.
There are many issues with FAQs in information-dense sites like Portland.gov:
- FAQs are seldom "frequently asked" questions, but instead represent information the editor wants to give the reader.
- These questions often duplicate content in other parts of the site, decreasing the efficacy of search.
- Humans want information in an order that can be understood: numerical, alphabetical, or time-based are the most common. This is difficult to do with FAQs because of the repeated grammar structures—for example, "How do I", "What do I", "Why do I", etc.
- Users of websites want to scan content. The cognitive load of looking for keywords in questions is higher than scanning simple page section titles.
Rather than using FAQs, consider a title followed by content structure similar to this style guide.
Using Related Content
Relate, don't repeat. Using content relation is a more robust way to refer to content on another part of the site. This will maintain the relationship even if the path for that content changes over time.
Use markup that explains the structure of the content. Headings are for showing sections and subsections of information.
Lists should be used for lists.
Embed documents and media using the media embed tools. These tools are represented by a paperclip (documents), image icon, play button icon (videos and audio), and a map icon. Embedding will give you formatting options that have been tested for accessibility and mobile device sizes.
Limit the use of bold and italics.
Use "title case" for titles and section headers. See examples on this page. Do not use a period at the end of the title/header.
Bureaus in title case on first reference (Bureau of Planning and Sustainability), with abbreviation in parens if used (BPS). Use the abbreviation or “the bureau” in subsequent references on the page. Use ampersands in the spelled version if that is the bureau’s preference (Portland Parks & Recreation, Portland Fire & Rescue).
Named professionals get title case on first reference (Mayor Jones) and when it is clear that a single person is being referenced (the Mayor (there is only one), the commissioners (there are four)).
Certified titles follow the name and comma as initials (Jane Jones, M.S.W.) unless convention dictates otherwise (PhD).
Portland is the “City of Portland,” “the City,” or “Citywide”; capitalize C in “Multnomah County”.
Old website is portlandoregon.gov; new site is Portland.gov.
Seasons are referred to in lower case (summer, winter) unless part of a title.
Refer to “ZIP code(s);” the word ZIP is an acronym (Zone Improvement Plan).
Numbers and Symbols
Abbreviate all street directionals without periods (e.g., SW); spell out if it appears in the street name (South Street). Spell the direction (Southeast) if there is no house number. House numbers use numerics only (i.e., 725 not Seven Two Five). Ordinals (“st,” “nd,” “th”) in lower case, not superscript.
Spell out numbers less than 10 and always to start a sentence; otherwise use numeric form.
Dates feature a comma before the year if they note the day (June 10, 1904; June 1904). Do not use ordinals (March 3, not March 3rd). Hyphenate date ranges, no space (May 12-14).
Times are expressed with a colon between hour, minutes, and seconds, and am and pm are both lower case without periods. Noon and midnight do not require a preceding “12.” Hyphenate time ranges, no space, and place the am or pm only after the later time.
Separate with a comma for four to six-digit numbers (1,000; 10,000; 100,000) but spell out words for larger numbers (million, billion). Spell out multipliers (hundreds not 100s) and indefinite numbers (thirty-some).
Refrain from using a hyphen (the - symbol) in situations that don't involve a hyphenated word, as when beginning a title with "Appeals-Commercial" or "Lecture Series-Part Three." Not only is it somewhat confusing for screen readers reading the text, but our search index will strip the hyphen and read them together as a single (non) word. The preferred separator is a colon, but most important is a space between the separator and the next word.
Apostrophes are for possession (cat’s paw), not plurals (rare jewels). When a group jointly possesses something, only the last subject gets a comma (Julie, Earl, and Mary’s apartment).
Oxford comma: YES! (Protein, fruit, and vegetables).
One space between sentences or after a colon.
Periods and commas go inside quotations, but outside parentheses if they end the sentence.
Semicolons go within a list of items with an internal comma, and to separate related sentence clauses where each clause could be a complete sentence itself.
Colons precede a list, an explanation, quote, or formal statement.
Use exclamation points sparingly.
Common Words and Phrases (When In Doubt, Check a Dictionary)
Biennial, biannual, semiannual: use “twice a year” or “every two years” instead as appropriate
Biodiesel, biofuel, biogas, biohazard (no hyphen)
Carbon emissions, not greenhouse gas emissions
Citywide and community wide (no hyphen), but bureau-wide (yes hyphen)
Climate change preparation, not climate adaptation
CO2 not CO2 or CO2
Database (one word), but data set (two words)
Eco-conscious, eco-friendly (yes hyphen), but ecoroof (no hyphen)
Email (no hyphen)
Fact sheet (two words)
Human-made (instead of man-made, and yes hyphen) or manufactured
Infill (no hyphen), but land use (two words)
Life cycle (two words)
Mixed-use development, mixed-use zones
Multifamily, multimodal (no hyphen)
Nonprofit (no hyphen)
Online, onsite, offsite: one word as adjective (onsite placement), but two as preposition (going off site)
Percent and percentile should be spelled out but may use ‘%’ or ‘%tile’ in tables and figures
Setback (as noun or adjective), set back (as verb)
Stormwater (one word)
Time frame, time line (two words)
Triannual, triennial: use “three times a year” or “every three years” instead as appropriate
Turnaround (one word)
Upstream (one word)
Watershed and waterborne (no hyphen)
Waste stream (two words)
Website (no hyphen); web page (two words)
Work flow (two words)
Yearlong (no hyphen), but year-round (yes hyphen)
Using URLs (links), Graphs, Tables, Figures, and Lists
URLs: refrain from referencing a web page by its URL address — find a brief, relevant title to use as the link text, and make the text into a clickable hyperlink instead, e.g. "Find more information in our help section."
Graphs: keep them simple, label the axes and outlier points. Keep vertical axis consistent across graphs if possible.
Tables: Leave no cells blank; use an em dash to fill. Write notes in lower case letters. Write titles in title case above table.
Figures: caption below the figure, left justified.
Lists, general: follow the natural order (alphabet, chronology).
Lists, run-in: keep short and separated by commas; longer lists should be marked with numbers (1) or letters (b).
Lists, vertical (bullet/ordered): If the list of items completes a sentence started by introductory text, make items lower case. If any item makes a sentence, capitalize and use punctuation on ALL items (otherwise do neither). Two columns for longer lists. If the items make a sequence (e.g., steps), use numbers instead of bullets.
Portland.gov-Specific Items to Note
Upload your documents to Portland.gov before linking or embedding them in your pages, rather than linking from external sites (including portlandoregon.gov).
Use “call to action” buttons sparingly, for those items where the user is doing something with an expected service result rather than looking up information or viewing media.
Buttons used for email contact should be labeled with the email address. (When possible, set up and use non-personal inboxes for receiving user email traffic).
Always fill in the alt-text area when uploading media; this is how screen readers are used to “see” media content.