Content

These guidelines aim to help everyone who writes for our products and create content that is clear, consistent and easy to understand. Good writing builds trust, improves usability and ensures our experiences feel cohesive across touchpoints.

General guidelines

These guidelines apply to all content–across platforms, products and mediums.

Content principles

Keep these principles in mind when writing content:

Keep it simple

• Use everyday language.
• Prefer short sentences and everyday words.
• Avoid jargon, acronyms, and overly technical terms (unless appropriate for the audience).
• Use short words and sentences

Be consistent

• Use the same term for the same concept throughout a product (and across products)
• If in doubt, search existing examples or ask in #ask-dataviz

Use labels generously

Headlines, descriptions and labels should communicate meaning and context clearly. Core concepts—such as “risk”, “claims”, “traceability” and “farm support”—are especially important and should be clearly and succinctly explained in their context. Expanded documentation should be linked to whenever possible. When annotating charts or explaining concepts, lean toward over- rather than under-explaining.

User interfaces

These guidelines apply to user interfaces.

Use sentence case

Use sentence-case capitalization for user interfaces. That means the first letter of a sentence is capitalized, proper nouns are capitalized, the rest of the sentence is in lowercase. When in doubt, don’t capitalize.

Use active voice

Use active voice when possible. This means the subject performs the action rather than receiving it, making sentences clearer and more direct. For example, instead of saying “This question was updated by Joe.” say “Joe updated this question.”

Prioritize action and clarity

When phrasing call to actions, help users quickly understand the purpose of an action by using clear specific verbs that describe what will happen, such as “Edit question” or “Delete file”. Avoid vague text like “Click here” or “Submit” as they give no context and force users to work harder to interpret the next step.

Provide useful error messages

Error messages should clearly state what went wrong and guide the user toward a solution in friendly, concise language. Avoid technical jargon or codes unless they are necessary and meaningful to the user. Where possible, offer specific, actionable steps so the user knows exactly how to resolve the issue.

Buttons and labels

Buttons and labels should be short and to the point, ideally no more than 1–3 words, always written in sentence case, and not include punctuation.