Community guidelines 2023 (#1924)

CONTRIBUTING.md

@@ -4,39 +4,61 @@
 
 ## How you can help
 
-- Submit pull requests with new snippets (see guidelines below) or snippet updates (tags, descriptions, explanations, typos, examples, code improvements).
-- Open issues for things you want to see added, modified, discuss ideas or help out with existing issues.
+- 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 modify snippet files**, never modify the generated files in the `snippet_data` directory.
-- **Use the snippet template** to create new snippets, ensure they have the correct name and are in the correct location.
-- **Follow snippet format exactly**, otherwise your snippets will not be recognized correctly by the tools responsible for publishing them on the website. This includes such things as spacing and empty lines - if you accidentally make a mistake, consult the repository's [snippet template](snippet-template.md).
+- **Only create or modify snippet and collecton 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.
 
 ## Snippet creation
 
 In order to create a new snippet, you should follow the steps below:
 
-- Create a copy of the [snippet template](snippet-template.md) in the `snippets` directory.
+- 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
 
 - Snippet must follow [these general writing guidelines](https://github.com/30-seconds/brand-and-design/blob/master/writing-guidelines.md).
-- Snippets must have all their frontmatter sections (title, tags etc.) filled.
-- Snippet titles must correspond to the filename and follow the language and repository's naming conventions.
+- 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 have their `firstSeen` dates formatted using [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
+- 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.
-- If your snippet contains arguments with default parameters, explain what happens if they are omitted when calling the function and what the default case is. Specify default parameters for arguments only if necessary.
-- If your snippet uses recursion, use the `recursion` tag and explain the base cases.
 - 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 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.
+- 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 habe 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.

collection-template.yaml

@@ -0,0 +1,14 @@
+slug: my-collection
+name: My awesome collection
+shortName: My collection
+featured: true
+snippetIds:
+  - js/s/array-initialization
+  - js/s/initialize-array-with-values
+  - js/s/initialize-array-with-range
+  - js/s/initialize-2d-array
+splash: plant-screen.png
+description: >-
+  Explain the collection's topic in a few sentences.
+shortDescription: >-
+  A short description of your collection up to 140 characters long.

snippets/articles/story-template.md

@@ -6,7 +6,7 @@ language: javascript
 tags: [webdev]
 author: chalarangelo
 cover: image
-excerpt: A short summary of your story up to 180 characters long.
+excerpt: A short summary of your story up to 140 characters long.
 dateModified: 2021-06-13T05:00:00-04:00
 ---
 

snippets/css/snippet-template.md

@@ -2,7 +2,7 @@
 title: Snippet Name
 type: snippet
 language: css
-tags: [other]
+tags: [layout]
 cover: image
 dateModified: 2021-06-13T05:00:00-04:00
 ---

snippets/css/story-template.md

@@ -0,0 +1,34 @@
+---
+title: My amazing story
+shortTitle: Amazing story
+type: story
+language: css
+tags: [layout]
+cover: image
+excerpt: A short summary of your story up to 140 characters long.
+dateModified: 2021-06-13T05:00:00-04:00
+---
+
+Explain briefly what the snippet does.
+
+- Explain briefly how the snippet works.
+- Use bullet points for your snippet's explanation.
+- Try to explain everything briefly but clearly.
+
+```html
+<div class="my-snippet"></div>
+```
+
+```css
+.my-snippet {
+  background-color: #fff;
+  border: 1px solid #000;
+  border-radius: 4px;
+}
+```
+
+```js
+console.log(
+  "This is optional, if your snippet doesn't require JavaScript, be sure to delete this block!"
+)
+```

snippets/git/story-template.md

@@ -0,0 +1,34 @@
+---
+title: My amazing story
+shortTitle: Amazing story
+type: story
+language: git
+tags: [branch]
+cover: image
+excerpt: A short summary of your story up to 140 characters long.
+dateModified: 2021-06-13T05:00:00-04:00
+---
+
+Explain briefly what the snippet does.
+
+- Explain briefly how the snippet works.
+- Use bullet points for your snippet's explanation.
+- Try to explain everything briefly but clearly.
+
+```html
+<div class="my-snippet"></div>
+```
+
+```css
+.my-snippet {
+  background-color: #fff;
+  border: 1px solid #000;
+  border-radius: 4px;
+}
+```
+
+```js
+console.log(
+  "This is optional, if your snippet doesn't require JavaScript, be sure to delete this block!"
+)
+```

snippets/js/story-template.md

@@ -0,0 +1,34 @@
+---
+title: My amazing story
+shortTitle: Amazing story
+type: story
+language: javascript
+tags: [array]
+cover: image
+excerpt: A short summary of your story up to 140 characters long.
+dateModified: 2021-06-13T05:00:00-04:00
+---
+
+Explain briefly what the snippet does.
+
+- Explain briefly how the snippet works.
+- Use bullet points for your snippet's explanation.
+- Try to explain everything briefly but clearly.
+
+```html
+<div class="my-snippet"></div>
+```
+
+```css
+.my-snippet {
+  background-color: #fff;
+  border: 1px solid #000;
+  border-radius: 4px;
+}
+```
+
+```js
+console.log(
+  "This is optional, if your snippet doesn't require JavaScript, be sure to delete this block!"
+)
+```

snippets/python/story-template.md

@@ -0,0 +1,34 @@
+---
+title: My amazing story
+shortTitle: Amazing story
+type: story
+language: python
+tags: [list]
+cover: image
+excerpt: A short summary of your story up to 140 characters long.
+dateModified: 2021-06-13T05:00:00-04:00
+---
+
+Explain briefly what the snippet does.
+
+- Explain briefly how the snippet works.
+- Use bullet points for your snippet's explanation.
+- Try to explain everything briefly but clearly.
+
+```html
+<div class="my-snippet"></div>
+```
+
+```css
+.my-snippet {
+  background-color: #fff;
+  border: 1px solid #000;
+  border-radius: 4px;
+}
+```
+
+```js
+console.log(
+  "This is optional, if your snippet doesn't require JavaScript, be sure to delete this block!"
+)
+```

snippets/react/snippet-template.md

@@ -2,7 +2,7 @@
 title: Component Name
 type: snippet
 language: react
-tags: [components,state,effect]
+tags: [hooks]
 cover: image
 dateModified: 2021-06-13T05:00:00-04:00
 ---

snippets/react/story-template.md

@@ -0,0 +1,34 @@
+---
+title: My amazing story
+shortTitle: Amazing story
+type: story
+language: react
+tags: [hooks]
+cover: image
+excerpt: A short summary of your story up to 140 characters long.
+dateModified: 2021-06-13T05:00:00-04:00
+---
+
+Explain briefly what the snippet does.
+
+- Explain briefly how the snippet works.
+- Use bullet points for your snippet's explanation.
+- Try to explain everything briefly but clearly.
+
+```html
+<div class="my-snippet"></div>
+```
+
+```css
+.my-snippet {
+  background-color: #fff;
+  border: 1px solid #000;
+  border-radius: 4px;
+}
+```
+
+```js
+console.log(
+  "This is optional, if your snippet doesn't require JavaScript, be sure to delete this block!"
+)
+```