Jump to: navigation, search

Difference between revisions of "Documentation/ReviewGuidelines"

m
m
Line 8: Line 8:
  
 
# Commit message
 
# Commit message
 +
## Content
 
## Conventions
 
## Conventions
 +
### Tags
 
## Spelling
 
## Spelling
## Tags
 
 
# Patch
 
# Patch
 
## Content
 
## Content
### Conventions
+
## Conventions
 
## Grammar
 
## Grammar
 
## Style/Phrasing/Wording
 
## Style/Phrasing/Wording

Revision as of 22:43, 28 April 2014

Goal

Provide guidelines to improve the quality and speed of the documentation review process.

Critique Categories

Objective

  1. Commit message
    1. Content
    2. Conventions
      1. Tags
    3. Spelling
  2. Patch
    1. Content
    2. Conventions
    3. Grammar
    4. Style/Phrasing/Wording
    5. Spelling

Subjective

  1. Patch
    1. Grammar
    2. Style/Phrasing/Wording
    3. Other suggestions

Consistency

  1. If you find an issue, do your best to mark all instances of it.
    1. 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.
    2. 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.
    3. 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.
    4. 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.
  2. 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.
    1. 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

  1. 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

  1. 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.
  2. 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.