Add short descriptions to contributor docs

contributor_docs/access.md

@@ -1,3 +1,5 @@
+<!-- What our commitment to access means for contributors and users of the library. -->
+
 # Our Focus on Access
 
 At the [2019 Contributors Conference](https://p5js.org/community/contributors-conference-2019.html), p5.js made the commitment to only add new features that increase access (inclusion and accessibility). We will not accept feature requests that don't support these efforts. We commit to the work of acknowledging, dismantling, and preventing barriers. This means considering intersecting[^1] experiences of diversity that can impact access and participation. These include alignments of gender, race, ethnicity, sexuality, language, location, et cetera. We center the needs of marginalized groups over the continued comfort of those privileged within the p5.js community. We are collectively exploring the meaning of access. We are learning how to practice and teach access. We choose to think of access through expansive, intersectional, and coalitionary frameworks. This commitment is part of the core values of p5.js outlined in our [Community Statement](https://p5js.org/community/).

contributor_docs/archive/custom_p5_build.md

@@ -1,3 +1,5 @@
+<!-- Instructions on how to combine just the p5.js modules you need into a single file. -->
+
 # Creating a custom build of p5.js with select components
 
 ## Overview

contributor_docs/archive/internationalization.md

@@ -1,3 +1,5 @@
+<!-- How we integrate translations into the p5.js codebase. -->
+
 # 🌐 Internationalization
 
 [Internationalization](https://developer.mozilla.org/docs/Glossary/Internationalization_and_localization) (sometimes abbreviated "i18n") refers to supporting multiple languages in a software project. This often means maintaining translations of text strings used in the project and letting users choose which translation they receive (or detecting it from their browser settings).

contributor_docs/archive/issue_labels.md

@@ -1,3 +1,5 @@
+<!-- A field guide to organizing p5.js GitHub issues. -->
+
 # p5.js issue labels
 
 p5.js uses a set of labels to help sort and organize issues.

contributor_docs/archive/supported_browsers.md

@@ -1,3 +1,5 @@
+<!-- How we decide what to support. -->
+
 # Supported browsers
 
 ## Our stated goal

contributor_docs/contributing_documentation.md

@@ -0,0 +1,41 @@
+<!-- A brief guide to the wide variety of ways you can contribute to the project. -->
+
+# Contributing Documentation
+
+Documentation is essential for new learners and experienced programmers alike. It helps make our community inclusive by extending a friendly hand to those who are less familiar with p5.js. It also helps us find the bugs and issues with the code itself, because we test and try things out as we document.
+
+There are several ways to contribute to documentation:
+
+## ☝️ Make changes
+If you're just getting started, one really helpful way you can contribute is by improving our documentation. If you notice a typo, a missing or broken example, or a function description that is confusing, here are some things you can do:
+* If you are just correcting a small typo, feel free to go ahead and work on it and send in a PR when you're finished! 
+* If you don't feel like fixing it yourself, that's alright. Let us know by [opening an issue](https://github.com/processing/p5.js/issues).
+* If you're unsure about anything, [open an issue](https://github.com/processing/p5.js/issues) anyway!
+
+## 🗯 Contribute to the reference  
+Read through the [reference](http://p5js.org/reference/), and look for typos, broken examples, or confusing documentation. If it's a straightforward fix, go ahead and work on it! If it's a more involved question that requires discussion, create an [issue](https://github.com/processing/p5.js/issues/new).
+* Here are instructions for [getting setup for the first time with the p5.js repo](./README.md).
+* The reference is built from the inline documentation in the source code (found in the `src/` folder).
+* Here is information on [how to update or add inline documentation and examples](./inline_documentation.md).
+* Here is the [documentation style guide](./documentation_style_guide.md) for writing and code samples.
+* If you find errors with the [spanish documentation](http://p5js.org/es), there are instructions to update this [here](https://github.com/processing/p5.js-website#internationalization-i18n-and-structure).
+* Community-maintained Typescript definitions are [here](https://github.com/p5-types/p5.ts).
+
+## ✨ Make examples  
+While the examples in the reference are meant to be very simplistic snippets of code, it is also useful to have longer, more complex examples.
+* Currently we are working on porting the examples from the [processing examples page](https://processing.org/examples/) to the [p5.js examples page](http://p5js.org/examples). If you would like to help with this, please see the instructions [here](https://github.com/processing/p5.js-website/blob/main/contributor_docs/Adding_examples.md).
+* Alternatively, you can create your own set of examples and publish them independently anywhere you like. If you share them online tag [@p5xjs](https://twitter.com/p5xjs) or email [hello@p5js.org](mailto:hello@p5js.org) to let us know, and we will share far and wide! This [guide to embedding p5.js](https://github.com/processing/p5.js/wiki/Embedding-p5.js) may be useful for posting your examples online.
+* If you find bugs in p5.js along the way, please log them in the [issues](https://github.com/processing/p5.js/issues).
+
+## 👯 Make tutorials 
+* If you are new to p5.js, this is a great place to start. Try making something yourself, then making a tutorial to teach others to do it too.
+* Currently we are working on porting the tutorials from the [processing tutorials page](https://processing.org/tutorials) to the [p5.js learn page](http://p5js.org/learn). If you would like to help with this, please see the tutorial on making tutorials [here](https://p5js.org/learn/tutorial-guide.html).
+* We also welcome tutorials on different subjects. You can publish these anywhere, in any format you like. If you share them online tag [@p5xjs](https://twitter.com/p5xjs) or email [hello@p5js.org](mailto:hello@p5js.org) to let us know, and we will share far and wide! We especially encourage tutorials created with a specific audience or use case in mind (ex: p5 for journalists, activists, poets, kids, seniors, dreamers, in a different language, etc). We like to consider, who does not already feel welcome or included in the p5 community, and can we use learning as an invitation? What is the language you use to communicate with your audience and make them feel known? Feel free to be experimental with your format. Check out [Sharon De La Cruz's talk on Code Slang](https://www.youtube.com/watch?v=CFT6w9NKfCs) for inspiration.
+* If you find bugs in p5.js along the way, please log them in the [issues](https://github.com/processing/p5.js/issues).
+
+## 👉 Getting started
+* Read the [p5.js community statement](http://p5js.org/community/)
+* Optional: Check out the [contributor docs](./README.md) to get an overview of the repository and learn how to build the code (if relevant for you).
+* All discussion happens on GitHub issues, so there's no slack/gitter/etc channel you need to join.
+* Add your name to the [contributors list](https://github.com/processing/p5.js#contributors) in the readme.md file! Instructions [here](https://github.com/processing/p5.js/issues/2309).
+* And of course, if you're more of a bug fixer kind of person, feel free to jump into any of the [issues](https://github.com/processing/p5.js/issues)!

contributor_docs/contributing_to_the_p5.js_reference.md

@@ -1,3 +1,5 @@
+<!-- A tour of the source code powering the Reference section of the p5.js website, and a guide to help contribute to it. -->
+
 # Contributing to the p5.js Reference
 
 In p5.js, we author the code reference you see on the [reference](https://p5js.org/reference/) page on the p5.js website by including them alongside the library’s source code as specialized comments. These reference comments include the description, the function’s signature (its parameters and return value), and usage examples. In other words, the content on each p5.js function/variable’s reference page is built from the reference comments in the source code.

contributor_docs/contributor_guidelines.md

@@ -1,3 +1,5 @@
+<!-- Start here if you are looking to participate on GitHub! -->
+
 # Contributor Guidelines
 
 Welcome to the contributor guidelines! This document is for new contributors looking to contribute code to p5.js, contributors looking to refresh their memories on some technical steps, or just about anything else to do with code contributions to p5.js.

contributor_docs/creating_libraries.md

@@ -1,3 +1,5 @@
+<!-- Step-by-step instructions on how to create an addon library. -->
+
 # Creating an Addon Library
 
 A p5.js addon library is JavaScript code that extends or adds to the p5.js core functionality. While p5.js itself already provides a wide range of functionality, it doesn’t aim to cover everything you can do with JavaScript and the Web API. Addon libraries let you extend p5.js without needing to incorporate the features into p5.js. This guide will take you through the steps of creating an addon library that loads a simple CSV file by implementing a `loadCSV()` function.

contributor_docs/design_principles.md

@@ -0,0 +1,12 @@
+<!-- High-level goals we keep in mind while building p5.js. -->
+
+# Design principles for p5.js
+
+- **Beginner Friendly** The p5.js API aims to be friendly to beginner coders, offering a low barrier to creating interactive and visual web content with cutting-edge HTML5/canvas/DOM APIs.
+
+- **Educational** p5.js is focused on an API and curriculum that supports educational use, including a complete reference to the API with supporting examples, as well as tutorials and sample class curricula that introduces core creative coding principles in a clear and engaging order.
+
+- **JavaScript and its community** p5.js aims to make web development practices more accessible to beginners by modeling proper JavaScript design patterns and usage, while abstracting them where necessary. As an open source library, p5.js also includes the wider JavaScript community in its creation, documentation and dissemination.
+
+- **Processing and its community** p5.js is a direct response to the Processing language and its community, and aims to make the transition from Processing to JavaScript easy and clear.  Supporting the Processing API and community is a priority for p5.js, while also expanding to include the new possibilities of creative coding on the web, and taking a Processing-style approach to exposing that API to beginners.
+

contributor_docs/documentation_style_guide.md

@@ -1,3 +1,5 @@
+<!-- A reference to help give our documentation a consistent voice. -->
+
 # Documentation Style Guide
 
 Hello! Welcome to the guidelines for writing p5.js documentation. This document is a remix of the following resources:

contributor_docs/fes_contribution_guide.md

@@ -1,3 +1,5 @@
+<!-- An overview of the Friendly Error System codebase and a reference for developers. -->
+
 # Friendly Errors System Contribution Guide
 
 The `core/friendly_errors` folder contains the code for the p5js’ Friendly Error Systems (FES) responsible for generating Friendly Error messages or Friendly Errors. You may have seen Friendly Error messages starting with “`🌸 p5.js says:`” in your console, supplementing default, browser-generated error messages.

contributor_docs/friendly_error_system.md

@@ -1,3 +1,5 @@
+<!-- An overview of the system used by p5.js to provide errors in friendly language. -->
+
 # 🌸 p5.js Friendly Error System (FES)
 
 ## Overview

contributor_docs/release_process.md

@@ -1,3 +1,5 @@
+<!-- How all the updates on GitHub get turned into a new version of the library. -->
+
 # Release process
 
 ## Approach

contributor_docs/steward_guidelines.md

@@ -1,3 +1,5 @@
+<!-- What to expect as a steward, and a playbook for common situations. -->
+
 # Steward Guidelines
 
 Whether you have just joined us as a steward, are a seasoned maintainer of p5.js, or are somewhere in between, this guide contains information as well as tips and tricks that will help you effectively contribute to p5.js. Most of what is written here are guidelines unless otherwise stated, which means you can adapt the practices shown here to suit your workflow.

contributor_docs/unit_testing.md

@@ -1,3 +1,5 @@
+<!-- Learn how to write tests for p5.js, and help us keep the library bug-free.  -->
+
 # Unit Testing
 
 Unit testing is an essential part of how a large codebase can stay relatively bug-free. Unit tests are small pieces of code that aim to test individual components of a larger code base for correctness. For example, making sure a function is doing what it should be doing or a class is creating its object instances correctly.

contributor_docs/web_accessibility.md

@@ -1,3 +1,5 @@
+<!-- The features p5.js provides to help keep sketches accessible to everyone. -->
+
 # p5.js Web Accessibility
 
 This document describes the structure of p5.js’ web accessibility features for contributors.

contributor_docs/webgl_contribution_guide.md

@@ -1,3 +1,5 @@
+<!-- How to get started working on the p5.js WebGL mode source code. -->
+
 # WebGL Contribution Guide
 
 If you're reading this page, you're probably interested in helping work on WebGL mode. Thank you, we're grateful for your help! This page exists to help explain how we structure WebGL contributions and to offer some tips for making changes.

contributor_docs/webgl_mode_architecture.md

@@ -1,3 +1,5 @@
+<!-- An overview of the design decisions that make up WebGL mode and their motivation. -->
+
 # p5.js WebGL Mode Architecture
 
 This document is intended for contributors and library makers who want to extend the WebGL codebase. If you are looking for help using WebGL mode in your sketches, consider reading the WebGL tutorials [on the p5.js Learn page](https://p5js.org/learn/) instead.