writing-guidelines.md

Writing guidelines

Language

• Use words and language that our 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.
• Use contractions to create a natural voice, but don’t overdo it with contractions that are hard to pronounce or aren’t used often.
• Conversely, not using a contraction can be used to add emphasis.
• Directional language (e.g. “above”, “below”) may only be used as part of a piece of content to indicate a relevant section of the content (e.g. “the above code example”).
• Prefer non-directional language if possible. Replace “above” and “below” for section indication with “previous” and “following”.

Voice

• Prefer writing in an active voice wherever possible.
• Avoid writing in a passive voice.
• Prefer a passive voice if you want to emphasize the action instead of the subject, clarify that an action wasn’t taken by a certain person or to avoid referring to the subject (i.e. the 30 seconds of code team or yourself).
• Use imperative voice when documenting 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") anywhere they’re used on the website.

Punctuation

• Avoid ampersands (&), as they focus attention in the wrong part of the sentence. Spell out the word “and” instead.
• Use apostrophes to represent omitted numbers or letters, contractions or to form possessives.
• Use quotation marks to define words or quoted text.
• Avoid using periods in the middle of sentences, unless it’s inside an inline code block or part of a term (e.g. "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.
• 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.
• The ellipses (...) can be used in place of a missing piece of text. Avoid using ellipses in regular text, use them only in headings.
• Avoid exclamation marks as much as possible. If you really have to use one, limit them to one per page.
• Avoid semicolons if possible. Try replacing them with a comma, the word “and” or splitting the sentence in two separate sentences.
• 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.

Terminology

• Use terminology sparingly and only when necessary.
• Only use industry-standard or well-established terminology.
• Explain terms if you’re not sure the reader understands them.
• Link to any relevant content on the website, if possible.

Emphasis

• Use bold sparingly to highlight important information on the page.
• Don’t use bold to create a heading.
• Use italics to quote text, usually in the form of short verbatim phrases.
• Use quotation blocks for longer sentences when you want to draw particular attention to them. Limit yourself to one quotation block per page.

Dates

• Use the American English format for dates ({month} {date}, {year}).
• Use the 3-letter abbreviation for months, followed by a period.
• Do not add nominal suffixes to date numbers.
• Don’t write dates numerically.

Code

• Wrap inline code blocks in the appropriate visual element.
• Wrap important values to the code such as numerals, strings or 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 that’s closest to the official documentation when describing native code (e.g. "Function.prototype.apply()").
• Do not use code blocks in headings.

Personal pronouns

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

Headings

• Capitalize the first word of a heading, lowercase the rest if the heading is 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 that are longer than one line.
• Limit headings to a single sentence. The only exception to this is headings that span multiple short questions.
• Headings need to be informative and descriptive.
• Avoid clickbait-type headings.
• Use headings that help the user understand what they’ll find in the related content.
• Use headings to make content easier to scan.
• Use a hyphen surrounded by a single space on either side for articles that are part of a series.
• For tip-type articles, start the heading with the word “Tip” followed by a colon and a space.
• Omit articles such as “the”, “a” and “an” in regular headings if possible.
• Omit articles such as “the”, “a” and “an” in microcopy.
• You can use ampersands (&) in microcopy headings to make the heading 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 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.

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 (e.g. Snippet, Article or Collection), prefer using the original heading of the content.
• 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 their surrounding context.

Alternative text

• 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.