Docs: Update documenation contributors guide with doc types (#36689)

* Update documentation contributors guide with types

- Adds new section that explains how the documentation is organized around types
- Updates headings to match sentence case as recommended
- Minor text tweaks and updates

* Markdown linting

docs/contributors/documentation/README.md

@@ -6,28 +6,37 @@ A guide on how to get started contributing documentation to the Gutenberg projec
 
 The [Make WordPress Docs blog](https://make.wordpress.org/docs/) is the primary spot for the latest information around WordPress documentation: including announcements, product goals, meeting notes, meeting agendas, and more.
 
-Real-time discussions for documentation take place in the `#docs` channel in [Make WordPress Slack](https://make.wordpress.org/chat) (registration required). Weekly meetings for the Documentation team are on Mondays at 14:00UTC.
+Real-time discussions for documentation take place in the `#docs` channel in [Make WordPress Slack](https://make.wordpress.org/chat) (registration required). Weekly meetings for the Documentation team are on Tuesdays at 14:00UTC.
 
 The Gutenberg project uses GitHub for managing code and tracking issues. The main repository is at: [https://github.com/WordPress/gutenberg](https://github.com/WordPress/gutenberg). To find documentation issues to work on, browse [issues with documentation label](https://github.com/WordPress/gutenberg/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22%5BType%5D+Documentation%22+).
 
-## Documentation Types
+## Documentation types
 
 There are two major sets of documentation for the Gutenberg project:
 
 1. [User documentation](https://wordpress.org/support/article/wordpress-editor/) is information on how to use the Editor as an author publishing posts. For contributing to user docs, follow the docs blog, or ask in the #docs Slack channel, to understand the current priorities.
-2. [Block Editor Handbook](https://developer.wordpress.org/block-editor/) is everything related to the Gutenberg project including: developing, extending, and—what you are reading right now—contributing specific to Gutenberg.
+2. [Block editor handbook](https://developer.wordpress.org/block-editor/) is everything related to the Gutenberg project including: developing, extending, and—what you are reading right now—contributing specific to Gutenberg.
 
-The rest of this document covers contributing to the Block Editor Handbook.
+The rest of this document covers contributing to the block editor handbook.
 
-## Block Editor Handbook Process
+## Block editor handbook process
 
-The Block Editor Handbook is a mix of markdown files in the `/docs/` directory of the [Gutenberg project repository](https://github.com/WordPress/gutenberg/) and generated documentation from the packages.
+The block editor handbook is a mix of markdown files in the `/docs/` directory of the [Gutenberg project repository](https://github.com/WordPress/gutenberg/) and generated documentation from the packages.
 
-An automated job publishes the docs every 15 minutes to the [Block Editor Handbook site](https://developer.wordpress.org/block-editor/).
+An automated job publishes the docs every 15 minutes to the [block editor handbook site](https://developer.wordpress.org/block-editor/).
 
 See [the Git Workflow](/docs/contributors/code/git-workflow.md) documentation for how to use git to deploy changes using pull requests. Additionally, see the [video walk-through](https://wordpress.tv/2020/09/02/marcus-kazmierczak-contribute-developer-documentation-to-gutenberg/) and the accompanying [slides for contributing documentation to Gutenberg](https://mkaz.blog/wordpress/contribute-documentation-to-gutenberg/).
 
-### Update a Document
+### Handbook structure
+
+The handbook is organized into four sections based on the functional types of documents. [The Documentation System](https://documentation.divio.com/) does a great job explaining the needs and functions of each type, but in short they are:
+
+-   **Getting started tutorials** - full lessons that take learners step by step to complete an objective, for example the [create a block tutorial](/docs/getting-started/create-block/README.md).
+-   **How to guides** - short lessons specific to completing a small specific task, for example [how to add a button to the block toolbar](/docshow-to-guides/format-api/README.md).
+-   **Reference guides** - API documentation, purely functional descriptions,
+-   **Explanations** - longer documentation focused on learning, not a specific task.
+
+### Update a document
 
 To update an existing page:
 
@@ -37,23 +46,23 @@ To update an existing page:
 4. Commit your changes.
 5. Create a pull request using "\[Type\] Documentation" label.
 
-### Create a New Document
+### Create a new document
 
-To add a new documentation page requires a working JavaScript development environment to build the documentation, see the [JavaScript build setup documentation](/docs/how-to-guides/javascript/js-build-setup.md):
+To add a new document requires a working JavaScript development environment to build the documentation, see the [JavaScript build setup documentation](/docs/how-to-guides/javascript/js-build-setup.md):
 
-1. Create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/HEAD/docs) folder, use lower-case, no spaces, if needed a dash separator, and .md extension.
+1. Create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/HEAD/docs) folder, use lower-case, no spaces, if needed a dash separator, and `.md` extension.
 2. Add content, all documents require one and only H1 tag, using markdown notation.
-3. Add item to the [toc.json](https://github.com/WordPress/gutenberg/blob/HEAD/docs/toc.json) hierarchy, see existing entries for format.
+3. Add document entry to the [toc.json](https://github.com/WordPress/gutenberg/blob/HEAD/docs/toc.json) hierarchy, see existing entries for format.
 4. Run `npm run docs:build` to update `manifest.json`.
 5. Commit `manifest.json` with other files updated.
 
 If you forget to run, `npm run docs:build` your PR will fail the static analysis check, since the `manifest.json` file is an uncommitted local change that must be committed.
 
-### Using Links
+### Using links
 
 It's likely at some point you'll want to link to other internal documentation pages. It's worth emphasizing all documents can be browsed in different contexts:
 
--   Block Editor Handbook
+-   Block editor handbook
 -   GitHub website
 -   npm website
 
@@ -69,7 +78,7 @@ Use the full directory and filename from the Gutenberg repository, not the publi
 
 An example, the link to this page is: `/docs/contributors/documentation/README.md`
 
-### Code Examples
+### Code examples
 
 The code example in markdown should be wrapped in three tick marks \`\`\` and should additionally include a language specifier. See this [GitHub documentation around fenced code blocks](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks).
 
@@ -94,16 +103,14 @@ The preferred format for code examples is ESNext, this should be the default vie
 
 **Note:** it is not required to include ES5 code examples. The guidance is to include `ES5` code for beginner tutorials, but the majority of code in Gutenberg packages and across the larger React and JavaScript ecosystem is in ESNext.
 
-### Callout Notices
+### Callout notices
 
 The Block Editor handbook supports the same [notice styles as other WordPress handbooks](https://make.wordpress.org/docs/handbook/documentation-team-handbook/handbooks-style-and-formatting-guide/#formatting). However, the shortcode implementation is not ideal with the different locations the block editor handbook documentation is published (npm, GitHub).
 
 The recommended way to implement in markdown is to use the raw HTML and `callout callout-LEVEL` classes. For example:
 
 ```html
-    <div class="callout callout-info">
-        This is an **info** callout.
-    </div>
+<div class="callout callout-info">This is an **info** callout.</div>
 ```
 
 The following classes are available: `info`, `tip`, `alert`, `warning`
@@ -124,8 +131,7 @@ This is an **alert** callout.
 This is a **warning** callout.
 </div>
 
-
-### Editor Config
+### Editor config
 
 You should configure your editor to use Prettier to auto-format markdown documents. See the [Getting Started documentation](/docs/contributors/code/getting-started-with-code-contribution.md) for complete details.