Skip to main content

Contribute to this site

Thanks for considering contributing to the project!

There's a link at the bottom of every page that says Edit this page. If you click it, you're taken to that docs page on GitHub where you can edit and submit a change right away.

Style guide​

This site uses the Google developer documentation style guide and the Microsoft Style Guide.

If you see anything that violates any of these style guides, please let me know by creating an issue on GitHub.

The four types of documentation​

This site hosts four types of documentation:

  • Tutorials are learning-oriented: they take the reader through a series of steps to complete a project. For example, Create your first plugin.
  • Guides are goal-oriented: they provide step-by-step instructions for how to solve a specific problem. For example, Settings.
  • Reference is information-oriented: its only job is to describe. For example, Plugin.
  • Concepts is understanding-oriented: they deepen the reader's understanding in a topic. For example, Workspace.

For more information, refer to The documentation system by Divio.

Tutorials​

Each tutorial should have the following structure:

  1. Description of what the reader will have accomplished after the tutorial.
  2. Prerequisites section that describes what the reader needs to complete the tutorial.
  3. Headings for each step that start with "Step X — " (that's an em-dash), followed by a sentence in imperative form. For example, "Step 3 — Submit plugin for review".
  4. Closing section that summarizes what the reader has accomplished, and where they can go next.

Guides​

Each guide should have the following structure:

  1. Description of the guide.
  2. Summary of what the reader will build or learn in the guide.
  3. Full code example
  4. Detailed explanation of the code example

The code block for the full code example must have a title with the filename, for example title="main.ts".

The example must be complete: the reader can copy-paste it into their own editor and run it without modifications.

For simpler code examples, use line highlighting to draw the reader's attention to the important parts.

For more complex code examples you may add one or more code blocks that duplicate sections of the full example, to allow for a more detailed explanation.