On 06/11/2011 11:08 AM, Eric H. Christensen wrote:
-----BEGIN PGP SIGNED MESSAGE-----
In my recent blog post I laid out a proposal for implementing Docs QA in a way that
will both help make sure that our guides and articles are correct and consistant and will
help get our new contributors on their way to contributing words to our guides.
The blog post was a proposal and was a derivative of various talks made with Fedora
contributors at SouthEast LinuxFest (SELF). The discussions were, unfortunately, closed
due to the lack of Docs contributors at SELF which is why I'm taking the time to bring
this proposal to the Fedora Docs community now for discussion.
I encourage everyone to reply with comments, questions, and perhaps a proposal of their
A few thoughts on this:
A Q.A. layer is a really good idea. It's always hard to check your own work.
I think for it work well it will need a formal test plan, with a
description of how to "test" a document.
Content and encoding are two separate concerns.
Content means documented instructions on using a product, such as
installation and configuration procedures. Those things can be tested in
isolation, if there is a good specification for things like a
pre-requisites section for procedures.
Encoding means the Docbook tags used to mark up the content. Testing
content and testing encoding are two distinct, but overlapping skillsets.
I'd say that these things are needed to do this:
1. Docbook tag style guide
2. Procedure format specification
3. Documentation Test plan
So authors use the Docbook tag style guide and Procedure format
specification to author, and then testers can follow the Test plan to
check the docs against that.
Content testers check the built output against the format specification,
and also test the procedure to make sure that the documented steps
produce the documented result.
Encoding testers check the source against the tag style guide.
Both could be done by the same person, but they should be done as two
separate passes. They are different, but related concerns.
- --Eric "Sparks"
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
-----END PGP SIGNATURE-----