Use plain language
- Put the most important information first.
- Use common words instead of formal or unusual ones.
- Keep to one idea per sentence.
- Spell out abbreviations the first time you use them, unless they’re widely known, such as API or SDK.
- Use the same words for the same things throughout a page.
Lead with the reader’s goal
Write from the reader’s point of view. Start with what they want to do or learn, then explain how. When a step has a purpose, state the purpose before the action.Give only the information the reader needs
Include details that help the reader finish the current task. Move background, history, and edge cases to their own section or page, and link to them. Describe what a feature does and how to use it. Don’t make claims about it.Write with confidence
State facts and instructions directly. Avoid hedging words such as “might,” “should be able to,” and “try to” unless the outcome really is uncertain. Be confident without being condescending.Always show the main answer
Keep the core instructions in the main flow of the page, not only inside tabs or accordions. See Writing for agents.Introduce complexity gradually
Start with the simplest path that works, then add options and advanced configuration. Explain why something matters before explaining how to do it. For example, a page about identity management should explain whatdistinct_id is and why it matters before it covers ID merge settings.
Avoid jargon
Use technical terms when your readers know them and the task needs them. Otherwise, use plain words. Define analytics and Mixpanel terms the first time you use them.Use the active voice and present tense
Say who does what. The active voice makes it clear whether the reader or Mixpanel takes an action.
Use the present tense to describe how the product works.
Address the reader as “you”
Write to the reader as “you.” Use “we” only when Mixpanel the company is doing something, such as “We store your data in the EU.” Don’t write “the user” when you mean the reader. In Mixpanel docs, “user” usually means the reader’s own customers.Be solutions-oriented
Anticipate where readers get stuck. Name common errors and their fixes on the page where they happen, and link to troubleshooting content. In troubleshooting content, name the cause, then the fix, and don’t blame the reader.Write clear, concise sentences
- Aim for sentences of about 20 words or fewer.
- Cut filler words such as “simply,” “just,” “easily,” “basically,” and “actually.”
- Avoid hype words such as “powerful,” “seamless,” “robust,” and “leverage.”
- Put one action in each step.
- Use contractions, such as “don’t” and “you’ll,” to sound natural.
- Don’t use exclamation points.
Write for the long term
Docs stay live for years. Avoid words that date a page, such as “now,” “new,” “currently,” “recently,” and “soon.” Describe how the product works, not how it changed, and announce changes in the changelog instead.Write accessible and inclusive documentation
Write so that everyone can read, navigate, and feel included by the docs, including people who use screen readers and other assistive technology. See Accessibility and inclusive language for the full rules.Write for a global audience
Many readers speak English as a second language or use translation tools.- Use simple sentence structures.
- Avoid idioms, slang, and cultural references, such as “out of the box” or “home run.”
- Write dates and times in the unambiguous formats in Grammar, punctuation, and formatting.
- Define terms instead of assuming readers know them.
Use consistent terminology
After you choose a term, keep using it. Don’t switch between “project token” and “project key” on the same page. See Terminology and product names for standard terms.Know your audience
Docs readers range from people new to analytics to experienced data engineers. People who know product analytics well may still be new to Mixpanel. Before you write, decide who the page is mainly for.
When a page serves both groups, put the steps everyone needs first, then add technical detail in its own section, a tab, or an accordion.