Documentation QA and Testing

Quick Checklist for Release Process

• Check wiki for info that is appropriate to be carried over to mion-docs
• New features or changes are documented, changelog checked
• Style-guide: Inclusive and supportive language, "mion" always lower case, other company and project names capitalized correctly.
• Links work correctly and point to appropriate target, and no "click here"
• Markdown renders correctly in a browser
• Docs for <docs.mion.io> render correctly with mkdocs and material theme
• Markdown files checked with markdownlint
• Accessibility checks used for <docs.mion.io>
• Step through any instructions
• Spelling and Grammar checked (It does not need to be perfect however)
• Concise, but not vague or ambiguous
• Doc site versioning is updated and waiting commit
• Copyrights and Licenses are present and correct

Overview

Documentation covers:

1. mion-docs
2. mion dev wiki
3. Repo based documentation.

All documentation must be checked that it follows the style guide. Markdown files should be checked with markdownlint, with exceptions made for line length. It is also recommended that documentation is checked for grammar and syntax. For vim, plugins such as ale can assist with this, the documentation maintainer can also assist with proofreading documents if you are unsure.

It is also advisable --and for mion-docs and any documentation with an image a requirement, that markdown is rendered locally before being published. Grip is a useful tool you can use for this, and follows GitHub flavored markdown.

All links must be checked to ensure they are working and pointing to the correct target.

Any documentation that provides instructions needs to be stepped through to check for accuracy, and to assure that any edge case is covered. Whenever possible, this should be done by someone other than the author. Feel free to ask the community, such as the general Slack channel, for volunteers.

The following subsections have QA steps that is specific to documentation type.

mion-docs

mion-docs has two paths in which documentation can be published. When opening a pull request to the dunfell branch, the general steps covered above are sufficient. Publishing directly to the gh-pages branch is primarily done by the documentation maintainer. Instructions for publishing to the gh-pages can be found in mion-docs/CONTRIBUTING.md; the QA steps are running a local instance of the mkdocs to ensure proper rendering, and running the accessibility checkers found in the style guide. As this branch is what gets published to <docs.mion.io>, the utmost care is required.

mion wiki

The wiki is aimed at providing documentation for development rather than users. Edits to the wiki are more lax than the published documentation, but the style guide should still be followed. It's also highly recommended that new pages to the wiki are reviewed by another contributor.

Repo Documentation

Repo documentation covers README files and any other documentation which can be found in one of the mion repos. It's important to check if any changes to a recipe/code that changes an interaction (such as parameters to the build script or new functionality) should be documented.