Addon Docs

Addon Docs, which is differentiated, but still related, to the general Docs (Scratch Addons Docs), is a section under /addons/ that contains documentation for addons. It is a way for general users to learn more about a specific addon, as well as reference for further development of the addon.

For addons without any subpage, each addon has a main page on /addons/[addon-id] and should be written on /content/addons/[addon-id].md, later will be called as "main addon page". For example, an addon with the ID my-favorite-addon has a main page on /addons/my-favorite-addon and is written on /content/addons/my-favorite-addon.md. The structure for addons with a subpage is different, so please read the "Subpages" section.

Read #260 for the previous discussion regarding the implementation.

Sections

These are the sections for the main addon page. These format of sections should be used, and if there isn't any applicable content on one of the sections, it may be skipped, including not writing the heading.

• Overview: Simple explanation describing the addon in general. Probably don't need a specific heading, just like the lead section on Wikipedia.
• Background: Reasoning/rationale/motivation and/or history of the implementation/addition of the addon.
• Features: Explanation of the available features inside the addon.
• Usage: Explanation of how to use the addon.
• Settings: Explanation of available settings.
• Compability: Information about compability, or browser/OS support.
• Future plans: Future work that will be done.
• Known issues: Known bugs and issues presents, including a link to the issue if necessary.
• Credit: Detailed credit/attribution.
• Changelog: List of changes for each addon. Ideally, this should be divided per version.
• Trivia: Witty notes or interesting things related to the addon.
• Gallery: Videos, screenshots, and other media that can't be included directly on the page.
• Related: Links to related pages. This includes issues, PRs, docs or other Addon Docs page, etc.

Subpages

Subpages are allowed. This is usually made for splitting a very long section, or adding more technical documentation for development reference ala what Scratch Addons Docs do with Scratch Addons.

Subpages are made with the file paths of /addons/[addon-id]/*, which the main page will be written on /content/addons/[addon-id]/_index.md and the subpages will be written on /content/addons/[addon-id]/[subpage-name].md.

If possible, links the subpage should be added in the main addon page.

An example is as follows.

• My favorite addon
  • Usage (from a longer section, for a very lengthy usage explanation)
  • Design (a technical documentation, including design considerations)

Front Matter

Due to limitations, at least id should be put in the main addon page, which will include the addon ID and should be the same as what is made on the path.

For example, an addon with the ID my-favorite-addon should have at least this on the front matter.

---
id: my-favorite-addon
---

Writing Guidelines

In general, the pages should be written similar to how Wikipedia articles are written, although there would be further considerations in the future.

Here are the non-exhaustive guidelines that applies on the Addon Docs as an highlight.

1. Bold the first mention of the addon name, which should be in the first sentence on the Overview section.
2. Use past tense on the changelog.