Content guidelines

​

Language

• Use words and language that the audience understands
• Use American spelling for all content
• Write short sentences (ideally 20 words or less)
• Make sure each sentence has a single focus
• Edit unnecessary or repeated words
• Avoid idioms and phrases with indirect or ironic meanings
• Avoid jargon and overly technical terms
• Aim for a Grade 10 reading level or below

​

Contractions

• Use contractions to create a natural voice, but don’t overdo it
• Avoid contractions that are hard to pronounce or aren’t used often
• Not using a contraction can add emphasis when needed

​

Directional language

• Directional language (“above”, “below”) may only indicate a relevant section of the content
• Prefer non-directional language when possible
• Replace “above” and “below” with “previous” and “following” for section references

​

Voice

• Prefer writing in an active voice wherever possible
• Avoid writing in a passive voice
• Use imperative voice when documenting code snippets (e.g. “use this method”)
• Don’t use permissive language (e.g. “you can use this method”)

​

Capitalization

• Capitalize the first letter of a sentence, lowercase the rest
• Keep the original capitalization of terminology (e.g. “JavaScript”), acronyms (e.g. “CRUD”), products (e.g. “GitHub Actions”) or trademarks (e.g. “Netlify”)

​

Punctuation

​

General rules

• Avoid ampersands (&) as they focus attention in the wrong part of the sentence. Spell out “and” instead
• Use apostrophes for omitted numbers or letters, contractions, or possessives
• Use quotation marks to define words or quoted text
• Avoid using periods in the middle of sentences (unless inside inline code or part of a term like “Node.js”)
• Use colons in the middle of sentences sparingly
• Use a colon to preface a list
• Use periods only to finish full sentences
• Use question marks sparingly. Try rewording to an affirmative if possible

​

Lists and sentences

• Do not use the oxford comma (also known as the serial comma) in sentences
• Don’t use commas to separate bulleted or numbered list items
• Avoid exclamation marks as much as possible (limit to one per page if necessary)
• Avoid semicolons if possible. Try replacing them with a comma, “and”, or splitting into two sentences

​

Hyphens and dashes

• Use hyphens without spaces for ranges
• Use hyphens in place of regular dashes inside a sentence with a space on either side
• Use hyphens to form compound modifiers

​

Code

• Wrap inline code blocks in the appropriate visual element
• Wrap important values (numerals, strings, boolean values) in the appropriate visual element
• Use multiline code blocks wherever the code spans more than one line
• Provide appropriate language context and highlighting to multiline code blocks
• Use the full name or the name closest to official documentation when describing native code (e.g. “Function.prototype.apply()”)
• Do not use code blocks in headings

​

Headings

• Capitalize the first word of a heading, lowercase the rest if formatted as a sentence
• You may capitalize the first letter of each word if the heading is not formatted as a sentence
• Avoid using punctuation such as periods, commas, colons or semicolons
• Headings may use a question mark if the content is a question-type article
• Keep headings short (avoid headings longer than one line)
• Limit headings to a single sentence
• Make headings informative and descriptive
• Avoid clickbait-type headings
• Use headings to make content easier to scan

​

Special heading formats

• Use a hyphen surrounded by a single space on either side for series articles
• For tip-type articles, start the heading with “Tip” followed by a colon and a space
• You can use ampersands (&) in microcopy headings to make them shorter

​

Lists

• Use bulleted (unordered) lists wherever possible
• Use numbered (ordered) lists for listicles or sequences of steps
• Prefer bulleted lists over numbered lists for documenting code snippets
• List items should start with a capital letter in all cases
• Don’t use commas or semicolons at the end of list items
• If any list item contains two or more sentences, punctuate all list items
• If all list items are one sentence or fragments, don’t punctuate
• Use bulleted lists to make content easier to scan

​

Personal pronouns

• Use “I” or “my” for personal opinions, experiences or expressing your personal voice
• Use “we” or “our” when referring to the 30 seconds of code team
• Use “we” or “our” when the audience is following along and you want to sound reassuring
• Use “you” or “your” when explaining something and you want to sound authoritative

​

Links and actions

• Actions should lead with a strong verb when possible (e.g. “Search”, “View all”)
• Capitalize the first word of an action, lowercase the rest
• Label links in a predictable way
• If a link leads to a page with its own heading, prefer using the original heading
• Links in full sentences should be applied only to the relevant text, not the entire sentence
• Links in full sentences must be descriptive, either on their own or based on surrounding context

​

Accessibility

• Provide alternative text for visual content whenever possible
• Use empty alternative text for decorative visual content
• Alternative text should help users navigate the site and provide an accessible experience
• Use plain language and avoid unnecessary words