Writing Clearly at Work: Messages, Documents and Decision Records

Most work now happens in writing: chat messages, email, shared documents, project notes. When that writing is unclear, people guess, ask follow-up questions or quietly do the wrong thing. Clear writing is one of the cheapest ways to make a team work better together.

The US federal government has spent years building practical guidance on this. The Plain Writing Act of 2010, as Digital.gov puts it, "established the requirement that content for the public is written for its specific audience." The government's long-running plain language website, PlainLanguage.gov, now points to a plain language guide series on Digital.gov, and its original guidelines are archived in a public GitHub repository. The advice was written for agencies, but it works just as well for a team of five.

This guide adapts that guidance to everyday work writing, then shows how to keep a simple record of team decisions.

Start with your reader

The core principle on Digital.gov is short: "Write for your audience." Before you write, ask who will read this, what they already know and what they need to do afterward.

Speaking directly to the reader helps. Digital.gov's writing guidance recommends active voice because it "makes it clear who should do what," and its example is a good one to remember: replace "It must be done" with "You must do it."

When a message or document has several audiences, consider separate sections for each, or separate messages. A note to the whole company about a new expense tool and a note to managers about approving expenses usually work better apart.

Put the main point first

Digital.gov's principles advise you to "Have a topic sentence" and to "Summarize lengthy documents up-front." Its design guidance adds: "Create logically structured pages with key information at the top."

In practice, lead with the request, decision or answer, then give context. Compare these two openings:

• Buried: "As you know, we've been looking at our phone options for a while, and after a lot of back and forth with the vendors..."
• Clear: "Please approve the new phone plan by Friday, November 6. It saves money and adds voicemail-to-email. Details below."

The second version lets a busy reader act after one sentence and read the rest only if they need it.

Keep it short and precise

Digital.gov recommends "shorter words" and "short sections." The archived federal guidelines go further on paragraphs: "Writing experts recommend paragraphs of no more than 150 words in three to eight sentences. Paragraphs should never be longer than 250 words." They also note that "There is nothing wrong with an occasional one-sentence paragraph."

A few other habits from Digital.gov's writing guidance make a large difference:

• Use active voice, so readers know who acts.
• Use the present tense, which "makes your writing simpler, more direct, and more forceful."
• Avoid hidden verbs. Say "analyze" instead of "conduct an analysis." Hidden verbs often end in "-ment, -tion, -sion, and -ance."

Requirements deserve special care. The archived federal guidelines recommend "must" for an obligation, "must not" for a prohibition, "may" for a discretionary action and "should" for a recommendation, and they advise against "shall," which they call imprecise because it "can indicate either an obligation or a prediction."

The same thinking applies to team norms. "Timesheets must be submitted by Monday at noon" is clearer than "Timesheets shall be submitted in a timely manner."

It also helps to pick one name for each thing and stick with it. If a document calls something the "client portal" in one paragraph and the "customer site" in the next, readers may reasonably wonder whether those are two different tools.

Format for scanning

People skim before they read. Digital.gov's design guidance recommends that you "Use lists for easy scanning," "Write heading terms that are clear and descriptive" and, where appropriate, "use tables to make complex relationships clear." It also warns that putting everything in capital letters is a poor way to add emphasis, because it makes text harder to read.

For work writing, that means descriptive headings in longer documents, numbered lists for steps, bullet lists for options, and a small table when you are comparing things across several dimensions.

Messages: email and chat

Short messages benefit from the same principles. A simple pattern:

1. Subject or first line: the action and the deadline, such as "Decision needed: booth size for the spring trade show, by Thursday."
2. The request in one sentence.
3. Only the context needed to act.
4. Options, if you are asking someone to choose, as a short list.
5. What happens next, and when.

In chat, put everything needed into one message instead of sending "Hi" and waiting for a reply. If the topic has grown long or complicated, move it into a shared document and link to it.

Decision records: writing down what you decided and why

Teams forget why they made decisions. Months later, someone asks "Why do we do it this way?" and nobody remembers. A decision record solves that.

One useful format comes from software. In a November 15, 2011 blog post, Michael Nygard proposed "architecture decision records" with five parts: a title, the context, the decision, a status and the consequences. He suggested writing the decision in "full sentences, with active voice," starting with "We will...," keeping each record "one or two pages long," numbering records sequentially without reusing numbers, and marking an old record as superseded rather than deleting it when a decision changes.

You can adapt that for any team. For example, imagine a small nonprofit deciding how volunteers sign up for shifts:

• Title: 007 Use a shared online sign-up form for volunteer shifts
• Status: Accepted, October 1
• Context: Phone sign-ups were missed after hours; two volunteers lack smartphones.
• Decision: We will use an online form, and the front desk will enter phone sign-ups into it.
• Consequences: Fewer missed sign-ups; front desk adds about one task a day; revisit in six months.

Keep records in one shared folder or page with a simple numbered list, so anyone can scan past decisions.

Test your writing

The archived federal guidelines describe paraphrase testing: ask a reader to stop at set points and explain, in their own words, what a section means. They suggest conducting six to nine interviews and advise avoiding yes-or-no questions. At work, a lighter version works: before sending an important announcement, ask one colleague to tell you what they think it asks them to do. If their answer surprises you, revise.

Key takeaways

• Write for a specific reader and tell them directly what they need to do.
• Put the request, decision or answer first, and the background after.
• Keep words, sentences and paragraphs short; use active voice and present tense.
• Use "must," "may" and "should" precisely, and stick to one term for each thing.
• Record team decisions with context, the decision, status and consequences.
• Test important writing by asking someone to explain it back to you.

Sources

• Digital.gov, Plain language guide series
• Digital.gov, Principles of plain language
• Digital.gov, Writing for understanding
• Digital.gov, Design for understanding
• PlainLanguage.gov archive (GSA), Write short paragraphs
• PlainLanguage.gov archive (GSA), Use "must" to indicate requirements
• PlainLanguage.gov archive (GSA), Paraphrase testing
• Michael Nygard (Cognitect), Documenting Architecture Decisions (November 15, 2011)