Difference between revisions of "Documentation/ReviewGuidelines"
Ionosphere80 (talk | contribs) (Built initial page) |
Ionosphere80 (talk | contribs) m |
||
Line 7: | Line 7: | ||
==== Objective ==== | ==== Objective ==== | ||
− | # Content | + | # Commit message |
− | # Conventions | + | ## Conventions |
+ | ## Spelling | ||
+ | ## Tags | ||
+ | # Patch | ||
+ | ## Content | ||
+ | ### Conventions | ||
## Grammar | ## Grammar | ||
## Style/Phrasing/Wording | ## Style/Phrasing/Wording | ||
− | # Spelling | + | ## Spelling |
==== Subjective ==== | ==== Subjective ==== |
Revision as of 21:06, 28 April 2014
Contents
Goal
Provide guidelines to improve the quality and speed of the documentation review process.
Critique Categories
Objective
- Commit message
- Conventions
- Spelling
- Tags
- Patch
- Content
- Conventions
- Grammar
- Style/Phrasing/Wording
- Spelling
- Content
Subjective
- Grammar
- Style/Phrasing/Wording
- Other suggestions
Consistency
- If you find an issue, do your best to mark all instances of it.
- If the author uploads a patch correcting your objective issue and you find another instance that you didn't mark, comment on it and score with a -1. Preferably, upload a patch to fix it.
- If the author uploads a patch correcting your subjective issue and you find another instance that you didn't mark, comment on it and score with a 0.
- If the author uploads a patch correcting your objective and/or subjective issue and you find another objective issue, comment on it and score with a -1. Preferably, upload a patch to fix it.
- If the author uploads a patch correcting your objective and/or subjective issue and you find another subjective issue, comment on it and score with a 0.
- If you find an issue that could affect other portions of a book, provide appropriate comments, score the patch with a -1, and consider mentioning your issue on the mailing list or in a meeting.
- Example: A new service uses "key = value" in the configuration file and all other services use "key=value" in their configuration files. Both methods work, but the book should maintain consistency.
The Waiting Game
- After the first review with a 0 or -1 score, how long should an author wait for additional reviews before addressing issues in the first review?
Considerations for Documentation Aligned with Release Cycles
- Beginning with milestone releases, shift focus to objective issues, especially with new services and existing services with significant changes. Only patches with significant subjective issues should receive a -1 score. Otherwise, comment on subjective issues and score with a 0.
- Beginning with release candidates, focus almost entirely on content issues. Only comment on subjective issues if the patch should receive a -1 score for objective issues.