CONTRIBUTING.md
# Contribution Guidelines
**30 seconds of code** is powered by the community, so feel free to contribute in any way you can to help us!
## How you can help
- Participate in community Discussions.
- Submit Pull Requests with new snippets or collections.
- Submit Issues or Pull Requests related to bugs, improvements, typos etc.
## Ground rules
Breaking any of these rules will result in your pull request being closed. Please follow these guidelines above all else:
- **Always be polite and respectful to others** and try to follow the advice of the moderators/collaborators/owners.
- **Only create or modify snippet and collection files**, never touch the `assets` or `languages` directories or any of the files in the root directory.
- **Use existing templates for snippets and collections**, ensuring to follow guidelines and that files are in the correct location.
- **Follow snippet and collection format exactly**, otherwise your content will not be recognized correctly by the tools responsible for publishing them on the website. Consult the templates or previous snippets/collections if you are unsure.
- **Snippets should solve real-world problems**, no matter how simple and should be abstract enough to be applied to different scenarios.
- **Stories should cover topics of interest to the community**, be well-written and concise, providing code examples as necessary.
- **Collections should be tied together by a common theme**, covering a narrow topic and providing a good number of snippets.
## Writing guidelines
All content on the website should follow the guidelines below. These guidelines are not exhaustive, but they should be followed as closely as possible.
### 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.
## Snippet creation
In order to create a new snippet, you should follow the steps below:
- Create a copy of the snippet or story template in the relevant subdirectory of the `snippets` directory and move it under the `s` directory.
- Change the name of the newly created file to the name of your snippet.
- Edit the file, adding your snippet based on the guidelines.
### Snippet guidelines
- Snippets must have all their frontmatter sections (title, tags, cover etc.) filled.
- Snippet filenames must be in `kebab-case` and end in `.md`. Use SEO-friendly names and avoid unnecessary words.
- Snippet titles must loosely correspond to the filename and follow the language and repository's naming conventions.
- Snippet tags must be comma-separated, contain a primary tag as seen on the website as their first tag.
- Snippets must include a cover image from the `assets/cover` directory, without the file extension.
- Snippets must have their `dateModified` dates formatted using [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
- Snippet descriptions must be short and to the point. Explain *what* the snippet does and detail *how* the snippet works and the language features used in it.
- Snippet code and examples must be enclosed in appropriate, language-tagged blocks as shown in the snippet template, be short and use modern techniques and features. Also make sure to test your code before submitting.
- Try to strike a balance between readability, brevity, and performance.
- Always use soft tabs (2 spaces), never hard tabs.
- Leave a single space after a comma (`,`) character (both in the description and code).
- Define multiple variables on the same line, if possible. Use meaningful variable names (e.g. `letter` instead of `lt`) and follow existing conventions as seen in other snippets. Do not use trailing or leading underscores in variable names.
- Whenever appropriate, an excerpt should be used to provide a short summary of the snippet. Excerpts should be up to 140 characters long and end in a period (`.`).
- Do not add or edit the `author` field in the frontmatter. This is reserved for organization members only.
## Collection creation
In order to create a new collection, you should follow the steps below:
- Create a copy of the collection template in the `collections` directory and move it under the relevant subdirectory.
- Change the name of the newly created file to the name of your collection.
- Edit the file, adding your collection based on the guidelines.
### Collection guidelines
- Collections must have all their metadata sections (title, splash, description etc.) filled.
- Collection filenames must be in `kebab-case` and end in `.yaml`. Use SEO-friendly names and avoid unnecessary words.
- Collection titles must loosely correspond to the filename and follow the language and repository's naming conventions.
- Collection descriptions must be short and to the point. Briefly explain the topic of the collection.
- Collection splashes must be images from the `assets/splash` directory, with the file extension.
- Collections must contain at least 3 snippets.