# General tips

Write in in US English.

# Write short, clear sentences

The shorter the sentence, the beter it is to understand. English is shorter than most languages; an average length English sentence may result in a long sentence when translated, impairing understanding.

# Be consistent

If you use a particular term for a particular concept in one place, then use that exact same term elsewhere, including the same capitalization. If you use different names for the same thing, translators may think you're referring to different concepts, and thus may use different translations.

Don't use the same word to mean different things. In particular, avoid using the same word as both a noun and a verb in close proximity.

# Don't be too culturally specific

In particular, don't refer to specific holidays, cultural practices, sports, etc., unless you're certain they're known worldwide. Avoid colloquialisms. Phrases like "ballpark figure," "back burner," or "hang in there" can be confusing.

# Accessible content

Write documentation with accessibility in mind, it improves the overall experience for all readers.

# Dos and don'ts

• Avoid ableist language. Avoid bias and harm when discussing disability and accessibility.
• Avoid unnecessary font formatting. (Screen readers explicitly describe text modifications.)
• Don’t force line breaks (hard returns) within sentences and paragraphs. Line breaks might not work well in resized windows or with enlarged text.
• Avoid camel case and all caps. Follow capitalization guidelines.
• Don't use & instead of and in headings and text.

# Reading ease

• Break up walls of text to aid in scannability. For example, separate paragraphs, create headings, and use lists.
• Use shorter sentences. Try to use fewer than 26 words per sentence.
• Define acronyms and abbreviations on first usage and if they're used infrequently.
• Use parallel writing structures for similar things.
• Place distinguishing and important information of a paragraph in the first sentence to aid in scannability.

# Headings and titles

Use descriptive headings and titles because they help a user navigate their browser and the page.

• Use a heading hierarchy.
• Don't skip levels of the heading hierarchy. For example, put an <h3> only under an <h2>.
• Don't have empty headings or headings with no associated content.
• Use a level-1 heading for the page title or main content heading.

# Links

• Use meaningful link text. Links should make sense when read out of context.
• Don't use click here or read this document.
• Avoid adjacent links or put a character between to separate them.

# Images

• For every image, provide alt text that adequately summarizes the intent of each image.
• Don't repeat images unless absolutely necessary.
• Don't present new information in images; always provide an equivalent text explanation with the image.

# Videos, recordings, and GIFs

• Avoid flickering or flashing elements. They can cause anything from motion sickness to a seizure.