NeoAnd/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2025-07-16 12:12:53 -06:00
Code Issues Actions 11 Packages Projects Releases Wiki Activity

Tweaks to docs quality standards

Jeff Gehlbach 2024-04-30 14:39:09 -04:00
parent b36c25f342
commit e1ac558bfc
1 changed files with 5 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
Plugin-Certification-Program.md

@ -75,17 +75,17 @@ NOTE: Only plugins using GitHub workflows for CI qualify at this time. Maintaine
#### Documentation quality #### Documentation quality
Every certified plugin's documentation and release notes must meet minimum criteria for quality, including: Every certified plugin's documentation and release notes must meet minimum criteria for quality, including:
- Plugin's top-level README must provide an outline of its full documentation which includes: - Plugin's top-level README should summarize the most salient points of its main documentation, and must include:
- A headline summarizing the plugin's value - A headline summarizing the plugin's value
- A concise introduction further breaking down the plugin's value so that a user can decide whether they might want to use it - A concise introduction further breaking down the plugin's value so that a user can decide whether they might want to use it
- A matrix of compatible plugin version ranges and NetBox version ranges - A matrix of compatible plugin version ranges and NetBox version ranges
- A list of any other NetBox plugins, Python libraries, external software, or external services that the plugin depends on for its operation, along with compatible version ranges for each such dependency. If no such dependencies exist, a simple "None" will suffice. - A list of any other NetBox plugins, Python libraries, external software, or external services that the plugin depends on for its operation, along with compatible version ranges for each such dependency. If no such dependencies exist, specify "None".
- One or more screenshots or screen recordings illustrating the plugin's value (exceptions are possible in case of plugins with very limited scope) - One or more screenshots or screen recordings illustrating the plugin's value (exceptions are possible in case of plugins with very limited scope)
- Brief installation instructions which do not assume deep user familiarity with plugins generally, and which when followed exactly will result in a functioning plugin. - Brief installation instructions which do not assume deep user familiarity with plugins generally, and which when followed exactly on a fresh installation of NetBox will result in a functioning plugin.
- A summary of where and how to engage with the plugin's maintainer team for bug reports, feature requests, and documentation requests (GitHub issues, Slack, etc.) - A summary of where and how to engage with the plugin's maintainer team for bug reports, feature requests, and documentation requests (GitHub issues, Slack, etc.)
- A summary of where and how to seek operational support as a user of the plugin (GitHub discussions, Slack, etc.) - A summary of where and how to seek support as a user of the plugin (GitHub discussions, Slack, etc.)
- The plugin's main documentation must treat each of the points in the README in further depth. To minimize redundancy, linking into the main documentation from the top-level README is encouraged, particularly concerning the concise introduction. - The plugin's main documentation must treat each of the points in the README in further depth. To minimize redundancy, linking into the main documentation from the top-level README is encouraged, particularly concerning the concise introduction.
- Plugin documentation may not consist solely of a top-level README unless the plugin's scope is exceptionally small. - Plugin documentation may _not_ consist solely of a top-level README unless the plugin's scope is exceptionally small.
- Plugin's release notes must open with a brief narrative summary characterizing it as a major, minor, or patch release and indicating whether it consists of bug fixes, new features, enhancements to existing features, or all of the above. - Plugin's release notes must open with a brief narrative summary characterizing it as a major, minor, or patch release and indicating whether it consists of bug fixes, new features, enhancements to existing features, or all of the above.
- Any time a release introduces breaking changes, the release notes must include a bold header reading *Breaking Changes* under which a brief summary of each such change is provided, including links to each relevant issue. - Any time a release introduces breaking changes, the release notes must include a bold header reading *Breaking Changes* under which a brief summary of each such change is provided, including links to each relevant issue.
- Plugin's release notes must include a changelog enumerating the issues resolved in the corresponding release. - Plugin's release notes must include a changelog enumerating the issues resolved in the corresponding release.