The Fedora Documentation Guide looks like the right place to put these kinds of things (procedure specification / documentation testing plan). I'd be happy to draft some content for that. Sound like a good idea? Another good source of material for that guide might be the JBoss Documentation Guide: https://hudson.jboss.org/jenkins/job/JBoss_Documentation_Guide/lastSuccessfulBuild/artifact/trunk/target/docbook/publish/en-US/html_single/index.html#sgp-Structure_Guidlines_Procedures - Josh On 06/13/2011 09:43 PM, Joshua Wulf wrote: > On 06/11/2011 11:08 AM, Eric H. Christensen wrote: >> -----BEGIN PGP SIGNED MESSAGE----- >> Hash: SHA256 >> >> In my recent blog post[0] 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 own. > > 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. > >> >> >> [0] http://fedora-sparks.blogspot.com/2011/06/fedora-docs-qa-process.html >> >> - --Eric "Sparks" >> -----BEGIN PGP SIGNATURE----- >> Version: GnuPG v1.4.11 (GNU/Linux) >> >> iF4EAREIAAYFAk3ywAoACgkQU03aaJDMNEUBlQD/cj+quMZ4414HKI4+0lGsvatL >> 26F7RY2zkLInoi04Qh0BAJzIhEmaQHNnS7PXlrAOnIx+xOnPa7td1qfwmLjOWgxx >> =8SBU >> -----END PGP SIGNATURE----- > > -- Give us your feedback on JBoss Enterprise Documentation, take the key survey: http://www.keysurvey.com/survey/361436/1065/ -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
