mirror of
https://github.com/privacyguides/privacyguides.org.git
synced 2024-12-18 04:14:37 -05:00
4bd9c6ca20
Signed-off-by: blacklight447 <niek@privacyguides.org> Signed-off-by: kimg45 <138676274+kimg45@users.noreply.github.com> Signed-off-by: Daniel Gray <dngray@privacyguides.org>
89 lines
5.2 KiB
Markdown
89 lines
5.2 KiB
Markdown
---
|
||
title: Writing Style
|
||
description: Our official writing style handbook for website contributors.
|
||
---
|
||
|
||
Privacy Guides is written in American English, and you should refer to [APA Style guidelines](https://apastyle.apa.org/style-grammar-guidelines/grammar) when in doubt.
|
||
|
||
In general the [United States federal plain language guidelines](https://plainlanguage.gov/guidelines) provide a good overview of how to write clearly and concisely. We highlight a few important notes from these guidelines below.
|
||
|
||
## Writing for our audience
|
||
|
||
Privacy Guides' intended [audience](https://plainlanguage.gov/guidelines/audience) is primarily adults who use technology. Don't dumb down content as if you are addressing a middle-school class, but don't overuse complicated terminology about concepts average computer users wouldn't be familiar with.
|
||
|
||
### Address only what people want to know
|
||
|
||
People don't need overly complex articles with little relevance to them. Figure out what you want people to accomplish when writing an article, and only include those details.
|
||
|
||
> Tell your audience why the material is important to them. Say, “If you want a research grant, here’s what you have to do.” Or, “If you want to mine federal coal, here’s what you should know.” Or, “If you’re planning a trip to Rwanda, read this first.”
|
||
|
||
### Address people directly
|
||
|
||
We're writing *for* a wide variety of people, but we are writing *to* the person who is actually reading it. Use "you" to address the reader directly.
|
||
|
||
> More than any other single technique, using “you” pulls users into the information and makes it relevant to them.
|
||
>
|
||
> When you use “you” to address users, they are more likely to understand what their responsibility is.
|
||
|
||
Source: [plainlanguage.gov](https://plainlanguage.gov/guidelines/audience/address-the-user)
|
||
|
||
### Avoid "users"
|
||
|
||
Avoid calling people "users", in favor of "people", or a more specific description of the group of people you are writing for.
|
||
|
||
## Organizing content
|
||
|
||
Organization is key. Content should flow from most to least important information, and use headers as much as needed to logically separate different ideas.
|
||
|
||
- Limit the document to around five or six sections. Long documents should probably be broken up into separate pages.
|
||
- Mark important ideas with **bold** or *italics*.
|
||
|
||
Source: [plainlanguage.gov](https://plainlanguage.gov/guidelines/design)
|
||
|
||
### Begin with a topic sentence
|
||
|
||
> If you tell your reader what they’re going to read about, they’re less likely to have to read your paragraph again. Headings help, but they’re not enough. Establish a context for your audience before you provide them with the details.
|
||
>
|
||
> We often write the way we think, putting our premises first and then our conclusion. It may be the natural way to develop thoughts, but we wind up with the topic sentence at the end of the paragraph. Move it up front and let users know where you’re going. Don’t make readers hold a lot of information in their heads before getting to the point.
|
||
|
||
Source: [plainlanguage.gov](https://plainlanguage.gov/guidelines/organize/have-a-topic-sentence)
|
||
|
||
## Choose your words carefully
|
||
|
||
> Words matter. They are the most basic building blocks of written and spoken communication. Don’t complicate things by using jargon, technical terms, or abbreviations that people won’t understand.
|
||
|
||
We should try to avoid abbreviations where possible, but technology is full of abbreviations. In general, spell out the abbreviation/acronym the first time it is used on a page, and add the abbreviation to the abbreviation glossary file when it is used repeatedly.
|
||
|
||
> Kathy McGinty offers tongue-in-cheek instructions for bulking up your simple, direct sentences:
|
||
>
|
||
> > There is no escaping the fact that it is considered very important to note that a number of various available applicable studies ipso facto have generally identified the fact that additional appropriate nocturnal employment could usually keep juvenile adolescents off thoroughfares during the night hours, including but not limited to the time prior to midnight on weeknights and/or 2 a.m. on weekends.
|
||
>
|
||
>And the original, using stronger, simpler words:
|
||
>
|
||
> > More night jobs would keep youths off the streets.
|
||
|
||
## Be concise
|
||
|
||
> Unnecessary words waste your audience’s time. Great writing is like a conversation. Omit information that the audience doesn’t need to know. This can be difficult as a subject matter expert so it’s important to have someone look at the information from the audience’s perspective.
|
||
|
||
Source: [plainlanguage.gov](https://plainlanguage.gov/guidelines/concise)
|
||
|
||
## Keep text conversational
|
||
|
||
> Verbs are the fuel of writing. They give your sentences power and direction. They enliven your writing and make it more interesting.
|
||
>
|
||
> Verbs tell your audience what to do. Make sure it’s clear who does what.
|
||
|
||
### Use active voice
|
||
|
||
> Active voice makes it clear who is supposed to do what. It eliminates ambiguity about responsibilities. Not “It must be done,” but “You must do it.”
|
||
|
||
Source: [plainlanguage.gov](https://plainlanguage.gov/guidelines/conversational/use-active-voice)
|
||
|
||
### Use "must" for requirements
|
||
|
||
> - “must” for an obligation
|
||
> - “must not” for a prohibition
|
||
> - “may” for a discretionary action
|
||
> - “should” for a recommendation
|