| layout | permalink | title | nav_order |
|---|---|---|---|
default |
/general/ |
General Principles |
2 |
{: .no_toc }
Table of contents
{: .text-delta } - TOC {:toc}All-purpose tips to help you write in any situation.
Use straightforward, approachable language that speaks directly to the reader.
Don't use unnecessary technical jargon or excessive formality.
Try to write sentences that flow naturally, as if you were speaking out loud.
Readers can read your words, but they can't read your mind. Each sentence should have an obvious subject, a logical sense of cause and effect (e.g., press X button to receive Y result), and no grammatical ambiguity.
When you start discussing a complex topic, try to provide a definition or other description context to help the reader understand what you mean and why the information is relevant to them.
Don't assume all readers have the same knowledge or expertise.
When all else fails, make a choice and stick to it.
Try to follow our style guide as much as possible—but if the style guide is inaccessible or doesn't provide guidance about a certain topic, at least use language that's internally consistent within the same document.
If you're not sure how to get started on a writing task, or if you feel like what you've written is missing something crucial, try asking yourself the following questions as you write.
It may seem obvious, but it's important to know what you're writing about.
Clearly define your topic by using a descriptive title and including an introductory paragraph at the beginning of your document. As you write, make sure each new section relates to this primary topic; if you find yourself veering too far off topic, you'll either need to broaden the scope of your document or break it down into several smaller documents.
You're writing for a reason—and readers read for a reason, too.
There are an endless number of reasons to write about any particular topic, but your answer will inform the type of content you're writing and how you're writing about it. For example, explaining how to use a tool requires different language, content, and formatting than persuading people to buy a tool. Whatever your goal is, make sure every part of your document supports it.
It's hard to write effectively if you don't know who you're writing for.
Although you should strive to use language that most readers can understand, the way you write may still change depending on your primary audience. Some audiences are experts in a topic; some audiences know very little about it. Some audiences are familiar with who we are; some audiences have never heard of our company before. Understanding the kind of people who will read your document can help you tailor your content to more effectively reach those readers.
Consider the circumstances that would lead someone to read your words.
Much like knowing your audience, it's important to anticipate the timing of when people will read your document. Content that's useful in one situation may not be useful in another—for example, a guide that explains how to prevent a boat from leaking won't offer much solace for someone whose boat is already halfway underwater. Understanding your readers' circumstances will help you tailor your writing to the current stage in their journey.
The best knowledge is applied knowledge.
Most writing exists to entertain, to inform, or both. When you're writing to inform, consider how a reader can apply the knowledge you're sharing with them. Some documents may provide the reader with a specific, actionable goal, like instructions for installing a new piece of software; other documents may simply raise awareness or explain a complicated topic. Whatever your intended goal is, be sure that the reader understands how your document will help them.