From Fedora Project Wiki
(Starting the page.) |
m (→What to look for when reviewing a guide: some revisions) |
||
| (6 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
This is the start to the Docs QA guidelines... | This is the start to the Docs QA guidelines... | ||
==What to | ==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 | ||
* Grammar | * 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 | |||
==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. | |||
[[Category:Docs QA]] | |||
Latest revision as of 17:24, 18 February 2013
This is the start to the Docs QA guidelines...
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
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.