Docs QA Review Guidelines

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
(Automation)
m (What to look for when reviewing a guide: some revisions)
 
Line 1: Line 1:
 
This is the start to the Docs QA guidelines...
 
This is the start to the Docs QA guidelines...
  
==What to look for when reviewing a guide==
+
==What to Look for When You Review a Guide==
 +
Note: This is an informal and incomplete list.
 +
* Compliance with [[Docs_Project_Style_Guide|Fedora Documentation Style Guide]]
 
* Broken links
 
* Broken links
 
* Appropriate license
 
* Appropriate license
 
* Misspelled words
 
* Misspelled words
* Repeated words (E.g. 'the the')
+
* Repeated words (E.g., 'the the')
* Grammar
+
* Grammar errors
* Compliance with Fedora Documentation style guide
+
* Documented procedures do what they say and do not cause problems
* Documented procedures do what they say they do without eating babies.
+
* Potential problems are given admonitions, where appropriate
  
 
==Automation==
 
==Automation==

Latest revision as of 17:24, 18 February 2013

This is the start to the Docs QA guidelines...

[edit] What to Look for When You Review a Guide

Note: This is an informal and incomplete list.

  • Compliance with Fedora Documentation Style Guide
  • Broken links
  • Appropriate license
  • Misspelled words
  • Repeated words (E.g., 'the the')
  • Grammar errors
  • Documented procedures do what they say and do not cause problems
  • Potential problems are given admonitions, where appropriate

[edit] Automation

Some of these checks can be automated, others by their nature can not. The script File:Qa check.sh provides an example of how DocBook XML might be automatically checked for:

  • Misspelled words
  • Repeated words

It also currently checks for use of entities outside the Feedback / Legal Notice / Book Info files. This script could also be extended to check for:

  • Broken links
  • Contractions
  • Suggestions welcome?

Usage:

  • Run qa_check.sh from within the book's root directory, for example musicians-guide/, to check the whole book.
  • Run qa_check.sh FILENAME to check a single file.