Oakland Answers: Content Style Guide


Oakland Answers is for everyone in Oakland. It has a welcoming and reassuring tone and aims to be a trusted and familiar resource. Many of our guidelines borrow from Gov.uk's valuable Content Style Principles, but this style guide is unique to Oakland Answers, catering both to its focus on answering questions conversationally as if speaking to a neighbor, yet also maintaining readability of the content.

TONE OF VOICE

Address the User

Users benefit from simple, direct language. Address the user as “you” where possible. Content on the site often makes a direct appeal to citizens and businesses to get involved or take action. E.g.:

“You can contact the Oaklanders Assistance Center by phone or email”

“Pay your parking ticket

Don’t use “we,” “I,” “our,” “us.”

Use Plain English

Use plain English – don’t use complicated or long words when easy or short ones will do. E.g.:

Use “buy” instead of “purchase”

Use “help” instead of “assist”

Use “about” instead of “approximately”

Use “like” instead of “such as”

Write content as simply as possible so that it is usable and accessible to everyone in Oakland, regardless of their language and vocabulary skills.

Write conversationally – picture your audience and write as if you were talking to them one-to-one but with the authority of someone who can actively assist.

Please note: use of plain English is mandatory for all sections of the site – all audiences should understand our content; this isn’t “dumbing down,” this is opening up government information to all.

Avoid Jargon

Avoid unnecessary jargon, legalistic prose, unexplained abbreviations or acronyms, rarely used Latin terms (“inter alia,” “ad hoc”), etc.

Sometimes it might be impossible to avoid unusual words or phrases – but these must be explained where possible.

When referencing a form, always give the English title of the form. E.g.:

“Application for Registration.”

Also, if there is a copy of the form online, link to it.


Use an Active and Positive Voice

Use the active rather than passive voice. This will help us write concise, engaging content.

When possible, word sentences as positives. E.g.:

Instead of, “No credit cards accepted” (both negative and passive voice)

Write, “Pay with personal check or cash”

Use Gender Neutral Text

Make sure text is gender neutral wherever possible. Avoid the awkward “his or her” situation. E.g.:

Instead of:  “A resident should take out his or her trash”

Write:  “Residents should take out their trash”


Be Concise

To keep content understandable, concise and relevant, it should be:

You should:

POINTS OF STYLE

Abbreviations and Acronyms

Spell out acronyms at first mention unless they’re well known (like the “FBI”).

In any article, the first time you use an abbreviation or acronym, explain it in full, and then refer to it by the acronym. E.g., “Department of Information Technology (DIT).” Don’t use an acronym if you’re not going to use it again later in the text.

Punctuation

Use “and” rather than an “&” unless as part of a brand name.

In a list of items do not add a comma before the “and” or “or” that precedes the last item. E.g., “democracy, government and citizenship.”

Use (round brackets), not [square brackets]. The only acceptable use of square brackets is for explanatory notes in reported speech. E.g., the Mayor said, “Thank you [Director] Bruce.”

Place quotation marks outside the period, comma, or bracket if the whole phrase is meant to be enclosed. But if only a part of the parenthetical text is quoted, the closing quotation mark should go inside. Also, for quotes within quotes, use single and double quotes to differentiate them. E.g.:

“Fill out the form first (but only after reaching the station).”

“Pay attention to popular terms (e.g., the verb 'register').”

Avoid using “/” to improve readability – where applicable, replace the slash with an “and” or “or.”

Bullet Points

How to use bullet points to make text easier to read:


Capitalization

DON’T USE BLOCK CAPITALS FOR LARGE AMOUNTS OF TEXT AS IT’S QUITE HARD TO READ.

The word “City” – as in “contact the City” or anywhere that City of Oakland could be substituted has a capital “C.”

Likewise, for job titles, specific departments, and other organizations, use initial capitals. E.g., “Customer Service Department.”



Numbers, Measurements, Dates, Times

Write all numbers in numerics (e.g., “the building has 5 floors”), except where it’s part of a common expression and would look strange (e.g., “One of them was always late to class”). Here’s an example showing the correct usage of both in the same sentence:

        “One should pause to think before climbing up 13 flights of stairs.”

If you have two unrelated numbers adjacent to each other, spell one of them to avoid confusion. E.g.:

        “Five 1-lb weights” or “5 one-lb weights”

For numbers over 9999, insert a comma for clarity – e.g., “10,000.”

For phone numbers, spell out the word “Phone:” before the number, (unless it's a part of a sentence). Always include the area code. E.g.:

“Phone: (510) 444-CITY

...with a space following the closing bracket.

Use a % sign for percentages – e.g., “50%.”

When referring to money, don’t use decimals unless cents are included – e.g., use “$75.50” but not “$75.00.”

Write out “cents” in full – e.g., “Calls will cost 4 cents per minute from a landline.”  And instead of “$0.25,” say “25 cents.”

Spell out dates – instead of “6/1/13,” write “June 1, 2013.”

Time is written in the following format: “5:30 pm” without any dots in “pm.”

Links and Email Addresses

Always offer links to online services first. Offer offline alternatives afterwards (where possible).

Make the link’s visible text as readable as possible:

An email address should be written out in full and always linked.

Hyphenation

In general, if in doubt, don’t use a hyphen unless the sense of the word is ambiguous without it.

For example, the following are non-hyphenated:

If “re” is followed by a word that starts with an “e” (e.g., “re-elect”), use a hyphen.

ARTICLE TYPES

On Oakland Answers, information is presented in 3 different ways:

ARTICLE TYPE:  QUICK ANSWER

Quick Answers provide concise answers to popular user questions. Less text, more specific answers.

Quick Answers address mainstream users’ needs. They assume prior knowledge and answer a popular – and specific – need (so you don’t need to explain terms or provide context). For example, the answer for “Local Minimum Wage rate” should only give the rate, not information about what the Local Minimum Wage is, nor how to pay it, etc. (although we should be clearly linking to related content that does).

Stick exclusively to the answer – don’t be tempted to include extra information, however useful this might appear to be.

Questions to Ask Yourself When Writing a Quick Answer

1.  What’s the general answer to the question?

Not the specific details, but the over-arching high-level answer. For example, if someone asked you how to transfer ownership of your car to someone else, you’d probably say, “You find the title and fill it out. Then you give it to the new owner, who fills out their information. Then they take it to the DMV to register the car in their name.”

The general answer to the question, or the most common answer to the question, may be a good introductory paragraph to the Quick Answer you’re writing. Here’s an example first sentence that answers the question, “How do I register a new motor vehicle?”:

“If you purchased the vehicle from an Oahu dealer, the dealer will probably have it registered and licensed for you. So you won't need to do anything further.”

  1. Is this a process?

Does a person follow a series of steps to achieve a specific goal? If so, try presenting this as a numbered list of short “You do X” sentences. Here’s an example:

Requirements at the DMV:

 1.        Bring your current license

 2.        Bring your proof of legal presence

 3.        Fill out an application form

 4.        Take an eye test

 5.        Pay with personal check or cash”

  1. Is the content similar or related, but not a series of steps?

Try presenting these items as a bulleted list. Here’s an example:

If you are completing registration on your own:

How to Organize a Quick Answer

First, the Quick Question:

Keep the question title short. Roughly 8 words will appear in search results, so think about which 8 words are going to best convey your question.

A Quick Answer can have 3 sections if needed. The top section is the only one that is required; for instance, you might have a Quick Answer that can be answered in the first paragraph without any additional content. Great, don’t add extra content to “fill out the page.”  

  1. Top section:

Use this to provide an answer for the most common users in the most common situations. Here’s the format:

One – or a couple of sentences – in Bold can go in this area. They either get the basic information out quickly, or they might be lead-in sentences to the answer:

  1. “What You Need To Know” section:

Use this section to flesh out some of the details for the summary in the top section. For example, you could explain a fee structure, or dates to be aware of, or a location the user needs to know about. You may also convey alternatives to an online transaction in this section.

Stay focused on the most common situations – if you start collecting a bunch of specific “If you are X” and “If you are Y” sentences here, you might want to create a Guide for the “If” content instead.

Be strict with information you include even if this means compromising caveats. Don’t stray off topic; stick to the question title.

Separate your main points (not one long paragraph). If you use subheads, title the subheading as similar to the Search Keywords as possible, and avoid questions for subheads.

There are also 3 invisible pieces of all article types (including Quick Answers) that need to be filled out:

1) Preview text:

2) Search keywords:

Consider all possible search keywords that people might use for the same Quick Answer. They could be synonyms or different phrasing of the question title. The “Search keywords” section should be filled out for words or phrases that aren't in the article text but might describe what the article is about.

For example, someone might search for “Business Tax” when looking for a “business license” related article. Since the term “Business Tax” doesn't appear in the article, you should include it in the “Search keywords” field.

Search keywords are separated by a space. Also, search queries are the same with or without the use of quotation marks.

3) Category:

Categories are logical citizen-focused topics that group articles around a common theme. See if there is an existing category this Quick Answer falls into. Or do you need to create a new category for it and other related articles?

Category names must be penned from the perspective of a citizen, and must not be department names.

Things to Keep in Mind When Writing a Quick Answer

Useful tips:

When Does a Quick Answer Become a Guide?

When the Quick Answer:

ARTICLE TYPE:  GUIDE

Guides are groups of information that are more lengthy or complex. Guides address specialist user needs in step-wise, bite-size chunks.

While Quick Answers give a single, concise answer, Guides have multiple pages of information around a topic. Guides have "parts" (sub-topics) on the left-hand side, allowing you to quickly access the relevant information.

Guides often encourage collaboration between departments to create a complete picture for the citizen user. E.g., a Guide on “Public Safety” would likely require collaboration between the Police Department, the Fire Department, Human Services, the Emergency Management Services department, etc.

First Part

“Part 1” of the Guide should contain the most important information that the majority of users will want to read – you can have an “Overview” but you don’t have to. Remember, every superfluous page we create is one more dead end for an angry, frustrated, confused user.

If you do have an “Overview” page, the following parts should contain more specific information as well as content for niche audiences.

Parts

Break content into parts based on expressed user needs (as well as the natural structure of the content).

You don’t have to use parts. If you find that you only have 3 or 4 small parts in a Guide, consider simply having a page without parts where users can scroll.

Each part should be a page. Each page should have similar amount of content so as to have consistent information design and be easy to parse visually.

In each part:

“Further Information” part:

A Guide should have no more than 7 parts. If a topic area has more sub-topics than 7, it should be broken down into two (or more) Guides.


Pointers

Use an “inverted pyramid” approach with the most important information at the top tapering down to lesser detail.

Paragraphs should have no more than 5 sentences each.

Large blocks of text should be split by regular subheaders.

Don't force a linear reading pattern. People should be able to read Part 4 before they read Part 2.

Stick to an upper limit of roughly 750 words – with case-by-case exceptions (e.g., some Budget pages).

Don't duplicate information but also don't assume people have read all parts of the Guide.

You can link between different parts of a Guide.

ARTICLE TYPE:  WEB SERVICE

Web Services are tools and transactional pages that enable you to complete tasks online and interact with government.

The format of a Web Service is very similar to that of a Quick Answer. The only difference is in the Top Section.

In a Web Service, the Top Section always has a big call-to-action button that links to the online form or service where the user can complete the task she is looking to perform. This Top Section is automatically created, and all you need to do for this section is to provide the URL that the button should link to.

The other sections are the same as for a Quick Answer.