Update examples.md for clarity

Author: SableRaf

docs/examples.md

@@ -1,18 +1,36 @@
 # Examples
 
-The content for the examples lives in `/content/examples` and are nested in folders named after the main category and the subcategory. The actual `.pde` files and the data associated with the Processing sketch are automatically copied from the [`processing-examples`](https://github.com/processing/processing-examples) repo while the rest of the content only live in this repo and should be edited here.
+The Processing website features [a selection of code examples](https://processing.org/examples) from the Processing software.
 
-Here is a quick overview of these files for the `Basic Examples > Image > BackgroundImage` example:
+The source files for these featured examples are located in `/content/examples`. Before you contribute to the [examples](https://processing.org/examples) page, it is important that you understand where these files come from. In the context of the examples page, there are two kinds of files:
 
-- `/content/examples/BackgroundImage/BackgroundImage.json` - This is the metadata for the example, and this file should be edited in this repo.
-- `/content/examples/BackgroundImage/BackgroundImage.png` - This is the image use on page listings and this file should be edited in this repo.
-- `/content/examples/BackgroundImage/liveSketch.js` - This is the P5.js live sketch code that runs on the example page, and this file should be edited in this repo.
-- `/content/examples/BackgroundImage/BackgroundImage.pde` - This file is synced from the `processing-examples` repo via a script and should \**not** be edited in this repo.
-- `/static/livesketch/backgroundimage` - This folder is the `data` folder for the example from the `processing-examples` repo and should \**not** be edited in this repo.
+1. Files specific to the website (like the thumbnail, or the metadata). These files \*should* be edited in this repository.
+1. Files automatically copied from the [`processing-examples`](https://github.com/processing/processing-examples) repo. These files should \*not* be edited in this repository. 
+
+For instance, the files for `Basic Examples > Image > BackgroundImage` are located at `/content/examples/Basics/Image/BackgroundImage/`. This folder contains the following files:
+
+| File Path                | Description                                                       | Edit here  |
+|--------------------------|-------------------------------------------------------------------|------------|
+| `BackgroundImage.json`   | Content file for the example ([jump to section](#content-file))                                 | ✅        |
+| `BackgroundImage.png`    | Cover image used on page listings ([jump to section](#cover-image))                            | ✅        |
+| `liveSketch.js`          | A manual port of the example to p5.js (real-time sketch running on the page)  | ✅        |
+| `BackgroundImage.pde`    | Processing code for the example (code shown on the page)          | ❌        |
+
+Additionally, if the original example had a `Data` folder, the contents of that folder are stored in `/static/livesketch/`. For `BackgroundImage`, you'll see a `/static/livesketch/backgroundimage` folder with a file called `moonwalk.jpg`. Do not edit this file ❌. Files in the `/static/livesketch/` folder are copied from the [`processing-examples`](https://github.com/processing/processing-examples) repo and should \*not* be edited in this repository
+
+## Which file(s) should edit?
+
+So you find an issue with an example on the website. Great! You are on your way to improving the Processing documentation and we are immensely grateful for your contribution! Here are the most common situations and the files you should edit.
+
+### Case 1: Issue with the live sketch
+If the sketch running on the website doesn't work as it should, especially if it doesn't match the behavior of the Processing code shown on the page, then you should edit the `livesketch.js` in the corresponding example folder. The live sketch is a manual port of the Processing sketch to p5.js, created by a human. Do \*not* try to edit the `.pde` file. That file is automatically copied from the [`processing-examples`](https://github.com/processing/processing-examples) and does not run in a browser.
+
+### Case 2: Issue with the code sample
+If there is a typo or any error in the code shown on an example page, head over to the [`processing-examples`](https://github.com/processing/processing-examples) repository and [create an issue](https://github.com/processing/processing-examples/issues) describing the problem. You can also submit a pull request with a fix. Check the instructions below on bringing changes from [`processing-examples`](https://github.com/processing/processing-examples) to this repo.
 
 ## Updating examples via script
 
-The Processing code for each example is copied via a script from the [`processing-examples`](https://github.com/processing/processing-examples) repo to website. The script will do two things: It will copy all `.pde` files into the `content/examples/TOPIC/SUBTOPIC/EXAMPLE` folder and it will copy all files in the `data` folder of the example into a `static/livesketch/EXAMPLE` folder. This makes it possible for the `liveSketch.js` sketch to load the original data. Some live sketches differ slightly from the original example (such as the AlphaMask example requiring a `.png` file instead of a `.jpg` file) and these files are manually place in the `static/livesketch-manual` folder.
+The Processing code for each example is copied via a script from the [`processing-examples`](https://github.com/processing/processing-examples) repo to website. The script will do two things: It will copy all `.pde` files into the `content/examples/TOPIC/SUBTOPIC/EXAMPLE` folder and it will copy all files in the `data` folder of the example into a `static/livesketch/EXAMPLE` folder. This makes it possible for the `liveSketch.js` sketch to load the original data. Some live sketches differ slightly from the original example (such as the AlphaMask example requiring a `.png` file instead of a `.jpg` file) and these files are manually placed in the `static/livesketch-manual` folder.
 
 **Note**: The script will only copy examples into the website that already have an existing `.pde` file. This means that the script will only update examples, not add new ones.