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.

Lead/Overview

This section is the lead of the page that contains a simple explanation of the addon in general. This is similar to the lead section on Wikipedia, including the fact that it doesn't require a specific heading.

Background

This section describes the background of the addon. Generally, it should include why the addon is made (reasoning/rationale/motivation) and the general history of the changes made to the addon (specifics should be made on the Changelog section).

Features

This section includes explanations of the available features that are implemented in the addon. As the general nature of the addons is atomic (can't be divided into multiple addons anymore), subheadings are not required. For large addons that can be divided into multiple, it is recommended to add subheadings.

Usage

This section includes guides/explanations on how to use the addon.

Settings

This section includes what settings that can be configured via the Settings page. It should have subheadings for each available settings. Not to be confused with the Features section.

Compability

This section includes any important compability information with other addons or specific browser or operating system. Availability on other forks are allowed.

Future plans

This section includes future work that may or will be done. Ideally, this should be linked to the related issue on GitHub.

Known issues

This section includes issues, including bugs, enhancements, etc that are known and will be fixed/implemented in the future. Ideally, this should be linked to the related issue on GitHub.

Credit

This section includes any past and present contributors, including a description of what each contributor did.

Changelog

This section includes a list of changes of each addon. Each item of the list (not including subitems) is one version. It is ordered chronologically, where the older versions are earlier on the list.

Trivia

This section includes witty notes or interesting things related to the addon.

Gallery

This section includes videos, screenshots, and other media that can't be included directly on the page.

Related

This section includes links to related pages. This includes issues, PRs (that are not covered on previous sections), 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
---

Warning

The front matter for subpages should follow the ones on the Docs. This haven't been tested, though. Your mileage may vary.

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, so following it is not strictly a requirement.

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.