City of Boston writing guide
We have tips for what to do — and what not to do — when writing content for the City of Boston.
What to do
Have an idea of who you want to provide the information to before you start. What you're writing should be like a conversation with a friend.Remember to use the active voice
For example, instead of writing, “The bill should be paid by the property owner,” we would write, “The property owner pays the bill.” It’s much more simple and direct.
An easy way to tell if you are using the active or passive voice is to add “by zombies” after the verb in the sentence. If the sentence still makes sense after adding “by zombies,” it’s in the passive voice. If not, it’s in the active voice. For example:
- Passive: The town was attacked (by zombies). Still makes sense.
- Active: Zombies attacked (by zombies) the town. Doesn’t make sense.
There are trickier versions of the passive voice, but this is an easy tip to keep in mind.
If a headline is longer than 11 words, it’s probably too long. Use full names and titles in headlines. Paragraphs should be two to three sentences at most. Aim for a sentence length of 15 to 20 words. For example:
- “Perhaps more important than fire fighting itself in many modern industrial countries is fire prevention,” could just be: “Fire prevention is important.”
Brevity can also increase readability and make the site more friendly for people using smartphones.Write for smaller screens
The more text, the more scrolling someone does on their smartphone or tablet.
Do you find yourself with a big paragraph? By breaking down your points into a bulleted list instead of a huge block of text, you’ll increase readability and comprehension. For example:
“The Fire Prevention Division, in the Boston Fire Department, directs fire prevention activities. It handles the more technical fire prevention problems, maintains appropriate records, grants permits, investigates the causes of fires, and conducts public education programs,” could just be:
“The Fire Prevention Division:
- handles more technical fire prevention problems
- maintains appropriate records
- grants permits
- investigates the cause of fires, and
- conducts public education programs.”
Just remember, you don’t have to bullet everything on a page. Only use bulleted lists when they make sense.
Don’t be afraid to say "we" instead of “The City.” Instead of "residents" or “applicants,” consider saying "you."Can we use a photo with the content?
Photos add depth to what you are talking about, and may provide greater context for users struggling with reading comprehension.Break up content into blocks or chunks
This allows readers to digest the content more easily. Ideally, you should separate these blocks of text with headlines and bullet lists of information.Write as you talk
This is a common rule in writing. The content that you create should be like a conversation between two people. Stuffy language can get in the way.
One of the easiest ways to write as you talk is with contractions. People talk in contractions — like can’t and don’t — and using them helps people relate to what you’re writing. The important thing to remember, though, is not to overuse them. Only use them when they sound natural.
What to avoid
We should be writing to the person with the least amount of knowledge on the topic. See a list of plain English words to use instead.Run-on sentences and multiple commas in a sentence
Use periods where you can to help a reader digest the content.Words like “may” and “shall”
When something needs to be done to complete a task, make sure a resident knows by using strong words like “must.”Acronyms
A human-centered website doesn’t require a government reference guide. Explain what it is you're talking about in detail.
While symbols — like “&” and “@” — can shorten your text, please just spell out what you’re writing. Symbols like these will only confuse your readers, especially those who may be learning English as a second language.Repetition
If the full title of person or place has been used already as a first reference on the page, we don’t have to repeat that full title. “Mayor Martin Walsh” would simply become “the Mayor” down the page.
Associated Press style
While there are some exceptions, we are using Associated Press, or “AP,” rules to guide our writing on the new site. A general Google search that includes “AP style” in the question will usually give you the right answer. Here are some common tips pulled directly from the AP stylebook:
Use the abbreviations Ave., Blvd., and St. only with a numbered address: 1600 Pennsylvania Ave. Spell them out and capitalize when part of a formal street name without a number: Pennsylvania Avenue. Lowercase and spell out when used alone or with more than one street name: Massachusetts and Pennsylvania avenues.
All similar words (alley, drive, road, terrace, etc.) always are spelled out. Capitalize them when part of a formal name without a number; lowercase when used alone or with two or more names.
Always use figures for an address number: 9 Morningside Circle. Spell out and capitalize First through Ninth when used as street names; use figures for 10th and above: 7 Fifth Ave., 100 21st St.
Always use Arabic figures for dates, without st, nd, rd, or th. For example:
- We were married on July 1, 2013.
- On September 5, we celebrate Labor Day.
For text used as a headline, only capitalize the first word and proper nouns. Use single quotes for quotation marks. For example:
- Neighborhood Development joins federal housing program
- Mayor Walsh names new director for Animal Control
- ‘Prepare for the storm,’ Mayor Walsh says
In general, spell out one through nine: The Red Sox finished first. He had nine months to go.
Use figures for 10 and above, and whenever preceding a unit of measure or referring to ages of people, animals, events, or things. For percentages, use numerals with “percent,” not “%”. For example:
- We picked more than 20 apples at the orchard.
- The City Council is revising the 8-year-old laws.
- We want you to spend 50 percent of your time on reading.
Use figures except for noon and midnight. Use a colon to separate hours from minutes. You don’t need the “:00” when referring to an hour of the day. For example:
- The meeting took place at 11 a.m., but we plan to meet again at 3:30 p.m.
When referring to a time span, please use a hyphen instead of the words “to” or “through.” For example:
- A typical work day for most people takes place from 9 a.m. - 5 p.m.
If you are writing about a time span in the afternoon, evening, or in the morning, you don’t need to write out the first a.m. or p.m. For example:
- We plan to discuss the proposal from 9-11 a.m. We should also set some time aside from 3-5 p.m.
Capitalize formal titles when they are used before one or more names: Pope Francis, President Barack Obama, Vice Presidents John Jones and William Smith.
Lowercase and spell out titles when they are not used with an individual’s name: The president issued a statement. The pope gave his blessing.
Lowercase and spell out titles in constructions that set them off from a name by commas. For example:
- The vice president, Joe Biden, was re-elected in 2012.
- Pope Francis, the current pope, was born in Argentina.
There are certain exceptions to this rule for the City of Boston, which you can find below.
Use figures, without commas, for years: 1975. Use an s without an apostrophe to indicate spaces of decades or centuries: the 1890s, the 1800s.
- January 1972 was a cold month. January 2 was the coldest day of the month.
- His birthday is May 8. February 14, 1987, was the target date.
- She testified that it was Friday, December 3, when the accident occurred.
Special writing rules
Always capitalize “Mayor” when referring to the Mayor of Boston. This is true whether or not you use the Mayor’s name. For example:
- Mayor Martin J. Walsh is coming to the meeting today.
- Martin J. Walsh, the Mayor of Boston, is coming to the meeting today.
- The Mayor is coming to the meeting today.
If you are talking about “mayors” in general, you do not need to capitalize the word. For example:
- Mayor Martin J. Walsh will be among the mayors who will visit the White House this week.
- Climate change is a big concern for mayors in many major cities along the coast.
Always capitalize “City Council” when referring to the Boston City Council. This is true whether or not you use “Boston” before “City Council.” For example:
- The Boston City Council will make a decision on the ordinance today.
- The City Council will make a decision on the ordinance today.
If you are talking about “city councils” in general, you do not need to capitalize the words. For example:
- In many major cities, city councils help enact laws.
Always capitalize “City” when referring to the City of Boston. For example:
- The City is ready for First Night.
- This time of year, students from around the world come to the City to attend college.
If you are talking about “cities” in general, you do not need to capitalize the word. For example:
- Boston is one of the major cities on the East Coast.
- Climate change is a big concern for cities across the United States.
Always use the “oxford” comma. If you use a serial list in your writing, please remember to include a comma before “and” at the end of the sentence. For example:
- Boston’s professional sports teams include the Patriots, Red Sox, Bruins, and Celtics.
Always use the click-to-call friendly format for phone numbers. Remember to use dashes so that the numbers are recognized on mobile devices. For example:
- Please use 617-353-4500, instead of (617) 653-4500, or 617.635.4500.
Plain English word listWord list
Here are some suggestions for plain language words to use instead of complicated jargon or legalese. We put together this list from a couple of different sources.
Looking for a better option for a complicated word? Click on a drawer below, hit (ctrl + f) on your keyboard, and type your word in. We might have an answer.
|INSTEAD OF:||CONSIDER USING:|
|(an) absence of||no, none|
|abundance||enough, plenty, a lot (or say how many)|
|accede||agree, grant, allow|
|access [verb]||enter, use, gain, entry|
|accommodation||where you live, home|
|according to our records||our records show|
|accustomed to||used to|
|acknowledge||thank you for|
|acquaint yourself||find out, read|
|address [sense 'consider']||tackle, deal with, consider|
|advise [ sense 'inform']||inform, tell, let [me] know|
|affix||add, write, fasten, stick on, fix to|
|afford an opportunity||let, allow|
|aforementioned, aforesaid||[get rid of or be more specific]|
|aforesaid||this, earlier in this document|
|aligned||lined up, in line|
|alleviate||ease, reduce, lessen|
|along the lines of||like, as in|
|alternatively||or, on the other hand|
|ambiguous||more than one meaning|
|annuity||pension, lifetime income|
|applicant||[use 'you' where possible]|
|apprise||inform, tell, let [me] know|
|appropriate (adjective)||suitable, right, proper|
|appropriate to||suitable for|
|as a consequence of||because|
|as of the date of||from|
|as regards||about, on the subject of|
|assemble||build, gather, put together|
|at an early date||soon (or say when)|
|at its discretion||can, may (or edit out)|
|at the moment||now (or edit out)|
|at the present time||now (or edit out)|
|attend||come to, go to, be at|
|attributable to||die to, because of|
|authority||right, power, may (as in "have the authority to")|
|axiomatic||obvious, goes with saying|
|by means of||by|
|calculate||work out, decide|
|circumvent||get around, void, skirt, circle|
|cognizant of||aware of, know about|
|cohort||group [with shared characteristics]|
|collaborate||work together, work with|
|commencement date||start date|
|commensurate with||consistent with|
|communicate||talk, write, telephone (be specific)|
|complete||fill in, finish|
|comply with||keep to, meet|
|comprise||make up, include|
|Instead of:||Consider using:|
|compulsory||required, you must|
|constitutes||makes up, forms, is|
|consult||talk to, meet, ask|
|contrary to||against, despite|
|corroboration||evidence, proof, support|
|costs the sum of||costs|
|cumulative||added up, added together|
|currently||now (or edit out)|
|deduct||take away, take off, substract|
|deem||treat as, consider|
|defer||put off, postpone|
|deliverables||results, outputs, what we'll provide|
|despatch or dispatch||send or post|
|despite the fact that||although, despite|
|determine [legal sense]||end, terminate|
|discharge [verb]||pay off, settle|
|disconnect [verb]||cut off|
|domiciled in||living in|
|due to the fact that||as, because|
|during which time||while|
|dwelling, domicile||home, property|
|economical||cheap, good value|
|egress||exit, way out|
|elect, election [outside of political context]||choose, choice|
|elucidate||explain, make clear|
|emanate from||come from, stem from|
|envisage||expect, imagine, forecast, think|
|equivalent||equal, the same|
|establish||set up, create, form|
|eventuate||result, occur, happen|
|ex officio||because of his or her position|
|exceptionally||only when, in this case|
|excessive||too many, too much|
|excluding||apart from, except|
|exempt from||free from|
|expedite||hasten, speed up|
|expeditiously||as soon as possible, quickly|
|extant||current, in force|
|fabricate||make, make up|
|Instead of:||Consider using:|
|failure to||if you do not|
|for the duration of||during, while|
|for the purpose of||to|
|for the reason that||because|
|forthwith||now, at once|
|forward [verb]||send, give|
|further to||after, following|
|generate||produce, give, make|
|give consideration to||consider, think about|
|henceforth||from now on, from today|
|hereby||now, by this (or edit out)|
|herein||here (or edit out)|
|hereinafter||after this (or edit out)|
|hold in abeyance||wait, postpone|
|hope and trust||hope, trust (but not both)|
|if and when||if, when (but not both)|
|if this is not the case||if so|
|immediately||at once, now|
|impart||give, pass on, tell, inform|
|implement [verb]||carry out, do|
|imply||suggest, hint at|
|in a number of cases||some (or say how many)|
|in accordance with||in line with|
|in addition (to)||and, as well as, also|
|in case of||if|
|in conjunction with||with|
|in connection with||for, about|
|in consequence||because, as a result|
|in excecss of||more than|
|in lieu of||instead of|
|in order to||to|
|in receipt of||get, have, receive, receiving|
|in relation to||about|
|in regard to||about, concerning, on|
|in respect of||about, for|
|in the absence of||without|
|in the course of||while, during|
|in the event of||if, when|
|in the eventuality of||if, when|
|in the majority of instances||most, mostly|
|in the near future||soon (or say when)|
|in the neighborhood of||about, around|
|in view of the fact that||as, because|
|incurred||have to pay, owe|
|insofar as||as far as|
|institute [verb]||being, start|
|interim [noun]||meantime, for the time being|
|irrevocable||cannot be reversed or change|
|irrespective of||despite, even if|
|is in accordance with||agrees with, follows|
|is of the opinion||thinks|
|it is known that||I/we know that|
|(a) large number of||many, most (or say how many)|
|(to) liaise with||to meet with, to discuss with, to work with (whichever is more descriptive)|
|mandatory||required by law, (you) must|
|may in the future||may, might, could|
|Instead of:||Consider using:|
|monies||money, amounts of money|
|moreover||and, also, as well|
|necessitate||need, have to, require|
|nevertheless||even so, however, yet|
|nonetheless||even so, however, yet|
|notify||tell, let us/you know|
|not less than (ten)||at least (ten)|
|not more than (ten)||(ten) or less, (ten) or fewer|
|notwithstanding||even if, despite, still, yet, but|
|numerous||many (or say how many)|
|(it is) obligatory||(you) must|
|occasioned by||caused by, because of|
|on behalf of||for|
|on numerous occasion||often|
|on receipt of||when we/you get|
|on request||if you ask|
|on the grounds that||because|
|on the occasion that||when, if|
|owing to||because of|
|(a) percentage of||some (or say what percentage)|
|participate||join in, take part|
|per annum||a year|
|peruse||read or study carefully, examine|
|previous||earlier, before, last|
|principal [adjective]||main, chief|
|procure||get, obtain, arrange|
|profusion of||plenty, too many (or say how many)|
|promptly||quickly, at once|
|provided that||if, as long as|
|provisions [of a law, policy]||the law, the policy, rules, terms|
|purport [verb]||pretend, claim, profess|
|pursuant to||under, because of, in line with|
|qualify for||can get, be able to get|
|reconsider||think again, about, look again at|
|referred to as||called|
|refer to||talk about, mention|
|(have) regard to||take into account|
|remainder||the rest, what is left|
|remuneration||pay, wages, salary|
|remunerative employment||paid work|
|render||send, make, give|
|representations||show, stand for, be|
|require||need, want, force|
|residence||home, property, address|
|review||look at (again)|
|Instead of:||Consider using:|
|scrutinize||read (look at) carefully|
|similarly||also, in the same way|
|shall [legal obligation]||must|
|specified||given, written, set|
|state||say, tells us, write down|
|statutory||legal, by law|
|stipulate||state, set, lay down|
|subject to||depending on, under, keeping to|
|substantial||large, great, a lot of|
|substantially||more or less|
|supplement||go with, add to|
|supply||give, sell, delivery|
|that being the case||if so|
|the law provides that||the law says|
|the question as to whether||whether|
|the way in which||how|
|thereby||by that, because of that|
|therein||in that, there|
|to date||so far, up to now|
|to the extent that||if, when|
|timeously||in goot time|
|tranche||slice, portion, share, chunk|
|ultimately||in the end, finally|
|undertake||agree, promise, do|
|until such time||until|
|virtually||almost (or edit out)|
|ways and means||ways|
|we have pleasure in||we are glad to|
|whatsoever||whatever, what, any|
|whereby||by which, because of which|
|whether or not||whether|
|with a view to||to, so that|
|with effect from||from|
|with reference to||about, concerning|
|with regard to||about, concerning|
|with respect to||about, for, concerning|
|with the minimum of delay||quickly (or say when)|
|you are requested||please|
|your attention is drawn||please see, please note|