Content guidelines

Writing guidelines for 30 seconds of code articles

All content on 30 seconds of code follows specific writing guidelines to ensure consistency, clarity and accessibility. These guidelines help maintain high-quality content across the entire collection.

Language

Write clear, accessible content that serves a global audience:

• 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

Write in an active, direct 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”)

Use passive voice only 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.

Capitalization

Follow sentence case throughout:

• 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

Format code consistently:

• 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

Write clear, scannable 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

Omit articles such as “the”, “a” and “an” in regular headings and microcopy if possible.

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

Format lists for easy scanning:

• 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

Choose pronouns based on context:

• 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

Make links predictable and accessible:

• 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

Ensure content is accessible to all users:

• 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