Back to top

City of Boston writing guide

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.

Still have questions? Contact:
Digital Team
1 City Hall Square, Room 703
Boston, MA 02201
United States

What to do

Write for your constituent first, always

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.

be short and to the point

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.

consider a bulleted list

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.

Personalize the experience for our constituents

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

jargon and government legalese

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.

Symbols

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:

Addresses

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.

Dates

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.
Headlines

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
Numerals

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.
Time

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.
Titles

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.

Years

Use figures, without commas, for years: 1975. Use an s without an apostrophe to indicate spaces of decades or centuries: the 1890s, the 1800s.

Some examples:

  • 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

Mayor

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.
City Council

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.
City

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.
Use the ‘Oxford’ comma

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.
Phone numbers

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 list

Word 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
accelerate speed up
accentuate strengthen, emphasize
access [verb] enter, use, gain, entry
accommodation where you live, home
accompanying with
accomplish do, finish
accordingly so
according to our records our records show
accountability responsibility for
accustomed to used to
acknowledge thank you for
acquaint yourself find out, read
acquiesce agree
acquire buy, get
additional more, extra
address [sense 'consider'] tackle, deal with, consider
adjacent next to
adjustment change, alteration
admissible allowed, acceptable
advantageous useful, helpful
advices information, instructions
advise [ sense 'inform'] inform, tell, let [me] know
affix add, write, fasten, stick on, fix to
afford an opportunity let, allow
afforded given
aforementioned, aforesaid [get rid of or be more specific]
aforesaid this, earlier in this document
aggregate [noun] total
aligned lined up, in line
alleviate ease, reduce, lessen
allocate give
along the lines of like, as in
alternative choice, other
alternatively or, on the other hand
ambit scope
ambiguous more than one meaning
ameliorate improve, help
amendment change
annuity pension, lifetime income
annul cancel
anticipate expect
apparent clear, obvious
applicant [use 'you' where possible]
application [noun] use
apportion split
appreciable large, great
apprise inform, tell, let [me] know
appropriate (adjective) suitable, right, proper
appropriate to suitable for
approximately about, roughly
as a consequence of because
as of the date of from
as regards about, on the subject of
ascertain find out
assemble build, gather, put together
assist, assistance help
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)
attain reach
attend come to, go to, be at
attributable to die to, because of
attribute [verb] earmark
authorize allow, let
authority right, power, may (as in "have the authority to")
axiomatic obvious, goes with saying
belated late
beneficial helpful, useful
bestow give, award
branchild idea
breach break
by means of by
burgeon grow, increase
calculate work out, decide
category group
cease stop, end
circumvent get around, void, skirt, circle
clarification explanation, help
cognizant of aware of, know about
combine mix
combined together
cohort group [with shared characteristics]
collaborate work together, work with
commence start, begin
commencement date start date
commensurate with consistent with
communicate talk, write, telephone (be specific)
competent able, can
compile male, collect
complete fill in, finish
comply with keep to, meet
component part
comprise make up, include
Instead of: Consider using:
compulsory required, you must
conceal hide
concept idea
concerning about
consequently so
considerable large
conclusion end
concur agree
condition rule
consequently so
considerable great, important
constitutes makes up, forms, is
construct [verb] build
construe interpret
consult talk to, meet, ask
consumption amount used
contemplate think about
contrary to against, despite
correct put right
correspond write
corroboration evidence, proof, support
costs the sum of costs
counter against
courteous polite
cumulative added up, added together
currently now (or edit out)
customary usual, normal
deduct take away, take off, substract
deem treat as, consider
defer put off, postpone
deficiency lack of
delete cross out
deliverables results, outputs, what we'll provide
demonstrate show, prove
denote show
depict show
designate name, specify
desire wish, want
desist stop
despatch or dispatch send or post
despite the fact that although, despite
determine decide
determine [legal sense] end, terminate
detrimental harmful
diminish lessen, reduce
disburse pay
discharge [verb] pay off, settle
disclose tell, show
disconnect [verb] cut off
discontinue stop, end
discuss talk about
disseminate spread
documentation papers, documents
domiciled in living in
dominant main
due to the fact that as, because
duration time, life
during which time while
dwelling, domicile home, property
economical cheap, good value
egress exit, way out
elect, election [outside of political context] choose, choice
eligible allowed, qualified
elucidate explain, make clear
emanate from come from, stem from
emphasize stress
empower allow, let
enable allow
enclosed inside, with
encounter meet
endeavor try, attempt
enhance improve
enquire ask
enquiry question
ensure make sure
entitlement right
envisage expect, imagine, forecast, think
equitable fair
equivalent equal, the same
erroneous wrong, mistaken
establish set up, create, form
evaluate test, check
eventuate result, occur, happen
evince show, prove
ex officio because of his or her position
exhaustive complete
exceptionally only when, in this case
excessive too many, too much
exclude leave out
excluding apart from, except
exclusively only
exempt from free from
expedite hasten, speed up
expeditiously as soon as possible, quickly
expenditure spending
expire run out
expiration end
extant current, in force
extremity limit
fabricate make, make up
Instead of: Consider using:
facilitate help
factor reason
failure to if you do not
finalize end, finish
following after
for the duration of during, while
for the purpose of to
for the reason that because
formulate plan, devise
forthwith now, at once
forward [verb] send, give
frequently often
fundamental basic
furnish give, provide
further to after, following
furthermore also
generate produce, give, make
give consideration to consider, think about
grant give
henceforth from now on, from today
hereby now, by this (or edit out)
herein here (or edit out)
hereinafter after this (or edit out)
hereof of this
hereto to this
heretofore until now
hereunder below
herewith with this
hitherto until now
hold in abeyance wait, postpone
hope and trust hope, trust (but not both)
hypothecate earmark
if and when if, when (but not both)
if this is not the case if so
illustrate show, explain
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 advance before
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
inappropriate wrong, unsuitable
inception start, beginning
incorporating which includes
incurred have to pay, owe
indicate show, suggest
inform tell
initially at first
initiate being, start
insert put in
instances cases
insofar as as far as
institute [verb] being, start
intend to will
interim [noun] meantime, for the time being
intimate say, hint
irrevocable cannot be reversed or change
irrespective of despite, even if
is in accordance with agrees with, follows
is of the opinion thinks
issue give, send
it is known that I/we know that
jeopardize risk, threaten
juncture point, time
(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)
locality place, area
locate find, put
magnitude size
mandatory required by law, (you) must
manner way
manufacture make
material relevant
materialize happen, occur
marginal small, slight
may in the future may, might, could
merchandise goods
mislay lose
modification change
Instead of: Consider using:
monies money, amounts of money
moreover and, also, as well
necessitate need, have to, require
negligible very small
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)
objective aim, goal
(it is) obligatory (you) must
obtain get, receive
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
onus burden, duty
operate work, run
optimum best, ideal
option choice
ordinarily normally, usually
other than except
otherwise or
outstanding unpaid
owing to because of
particulars details, facts
(a) percentage of some (or say what percentage)
partially partly
participate join in, take part
particulars details, facts
per annum a year
perform do
permissible allowed
permit let, allow
personnel people, staff
persons people
perpetrator (alleged) wrongdoer
peruse read or study carefully, examine
polemical controversial
possess have, own
possessions belongings
predominantly mainly
prescribe set, fix
preserve keep, protect
previous earlier, before, last
principal [adjective] main, chief
prioritize rank
prior to before
proceed go ahead
procure get, obtain, arrange
profusion of plenty, too many (or say how many)
prohibit ban, stop
projected estimated
prolonged long
promptly quickly, at once
promulgate advertise, announce
proportion part
provenance source, origin
provide give
provided that if, as long as
provisions [of a law, policy] the law, the policy, rules, terms
proximity closeness, nearness
purchase buy
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
reduce cut
reduction cut
referred to as called
refer to talk about, mention
(have) regard to take into account
regarding about
regulation rule
reimburse repay
reiterate repeat, restate
relating to about
remain stay
remainder the rest, what is left
remittance payment
remuneration pay, wages, salary
remunerative employment paid work
render send, make, give
representations show, stand for, be
representations comments
request ask, question
require need, want, force
requirements needs, rules
reside live
residence home, property, address
restriction limit
retain keep
review look at (again)
revised new, changed
save [conjunction] except
Instead of: Consider using:
scrutinize read (look at) carefully
select choose
settle pay
similarly also, in the same way
shall [legal obligation] must
solely only
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
submit send, give
subsequent to/upon after
subsequently later
substantial large, great, a lot of
substantially more or less
sufficient enough
supplement go with, add to
supplementary extra, more
supply give, sell, delivery
terminate end, stop
that being the case if so
the law provides that the law says
the question as to whether whether
the way in which how
thereafter then, afterwards
thereby by that, because of that
therein in that, there
thereof of that
thereto to that
thus so, therefore
to date so far, up to now
to the extent that if, when
transfer change, move
transmit send
timeously in goot time
tranche slice, portion, share, chunk
ultimately in the end, finally
unavailability lack of
undernoted the following
undersigned I, we
undertake agree, promise, do
uniform same, similar
unilateral one-sided, one-way
unoccupied empty
until such time until
utilization use
utilize use
variation change
verify check, prove
virtually almost (or edit out)
visualize see, predict
ways and means ways
we have pleasure in we are glad to
whatsoever whatever, what, any
whensoever when, whenever
whereas but
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)
whilst while
willfully deliberately
you are requested please
your attention is drawn please see, please note
zone area, region