> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Chalarangelo/30-seconds-of-code/llms.txt
> Use this file to discover all available pages before exploring further.

# 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")

<Note>
  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.
</Note>

## 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

<Warning>
  Omit articles such as "the", "a" and "an" in regular headings and microcopy if possible.
</Warning>

### 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