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