Update CONTRIBUTING

CONTRIBUTING.md

@@ -37,12 +37,16 @@ New extensions should be added in a user folder. You can name your folder anythi
 
 Extensions must be self-contained. All libraries and hardcoded resources should be embedded into the extension's JavaScript file. If you include minified code, please link where to find the unminified code and include a copy of the original license.
 
-Static resources go in the `website` folder. This is where some example assets used by extensions such as fetch are placed. This is also where documentation goes for now, though we are in the process of modernizing that.
+## Website stuff
 
 To add an extension to the website homepage, modify [`website/index.ejs`](website/index.ejs). See the existing entries for a template to copy. Place your extension wherever you want in the list. We will move it for you if we disagree.
 
 New extensions do not *need* images, but they are highly encouraged. Save the image in the `images` folder with the same folder name and file name (but different file extension) as the extension's source code. For example, if your extension is located in `extensions/TestMuffin/fetch.js`, save the image as `images/TestMuffin/fetch.svg` or `images/TestMuffin/fetch.png`. The homepage generator will detect it automatically. Images are displayed in a 2:1 aspect ratio. SVG (preferred), PNG, or JPG are accepted. PNG or JPG should be 600x300 in resolution. Please add proper attribution to `images/README.md` for *any* resources that were not made by you.
 
+Most extensions shouldn't need external documentation -- it should be obvious what to do just by looking at the blocks. That said, some do need more explanation. Documentation is written in markdown and placed in the `docs` folder with a similar layout to images. For example, documentation for `extensions/TestMuffin/fetch.js` would be saved as `docs/TestMuffin/fetch.md`. Our version of markdown is slightly extended to allow rendering [scratchblocks](https://scratchblocks.github.io/). Just look at the existing documentation for examples. It's not a perfect experience: block colors have to be manually copied, and icons aren't supported, but it's better than what we had before.
+
+Static resources, such as example links, go in the `website` folder. This is where some example assets used by extensions such as fetch are placed.
+
 ## Banned APIs
 
 (subject to change)