Gennadiy, Initial comments (IMO) so far: It might be worthwhile including a section at the beginning to list the standard acronyms and provide a definition for any common terms you use throughout the documentation. There are several instances so far where you use an acronym without specifying what it is. FAQ: "Where the latest version of the Boost Test Library is located?" should read "Where can I find the latest release of the Boost Test Library and Documentation?" - Under this then have these sentences: + "The latest version of the Boost Test Library documentation can always be found online at http://www.boost.org/libs/test" + "To download the latest release of the Boost Test Library code please follow the instructions detailed in the Getting Started Guide located at http://www.boost.org/more/getting_started.html" - It might also be worthwhile adding something here for getting the latest code from Subversion? "I found a bug. Where can I report it?" - To encourage good behaviour it might be worth adding these points under this heading: + To ensure that the author of the library fixes the bug please submit a bug report by: * Submitting a new trac ticket at http://svn.boost.org/trac/boost/newticket. Please ensure that you select the correct milestone and version of boost you are using. It is important that you also select "Test" as the component to ensure speedy notification. * In addition to the above you can send a bug report to the boost users/developers mailing list and/or directly to me (include email address) "I have a request for a new feature. How can I ask for it?" - To encourage good behaviour it might be worth adding these points under this heading: + To ensure appropriate tracking of the feature request it is important to submit this to our tracking database by: * Submitting a new trac ticket at http://svn.boost.org/trac/boost/newticket. Please ensure that you select "Feature Request" in the type of the request. It is important that you also select "Test" as the component to ensure that this is tracked against the Unit Test Framework. * In addition to the above you can send a feature request to the boost users/developers mailing list and/or directly to me (include email address) "How to create test case using the UTF?" - If I am a newbie looking at the Test Library FAQ am I already expected to know what the acronym "UTF" stands for? Also is UTF a standard keyword to search for if I already know about Test Driven Development (TDD)? Looking at the current(/old) FAQ it seems that UTF standards for Unit Test Framework. - It might be worthwhile to rename this to something like "What is the simplest way to write a test in the Boost Test Library?" "How to create test suite using the UTF?" - Similar comments to the above. - Maybe rename this to "What is the easiest way to group similar tests in the Boost Test Library?" --- [ End comments so far ] --- This is as far as I have gone so far I will try to get some more time tomorrow night. If you make the BoostBook file available I will try to update this and then you can do a diff and work out which changes are relevant. Thanks, Peter. -
----------------------------------------------------------------------
Message: 1 Date: Sun, 12 Aug 2007 05:26:51 -0400 From: "Gennadiy Rozental" <rogeeff@gmail.com> Subject: [boost] Boost.Test documentation update; alpha release To: boost@lists.boost.org Cc: boost-users@lists.boost.org, boost-docs@lists.boost.org Message-ID: <f9mjom$kgo$1@sea.gmane.org>
Hi,
I've finally been able to produce alpha release of completely reworked BoostBook based documentation for Boost.Test library. It's still not ready for release and I expect significant changes in both L&F (once I apply latest IBD based style) and content (some articles still missing). But it's in a shape close to what I would like it to be.
I would really appreciate any comments to both content (language including) and style. I realize it might not be small undertaking so if you have time for just part of it, please post comments as well.
The release is available here:
patmedia.net/~rogeeff/html/index.html
in patmedia.net/~rogeeff/src you can find sources.
Thank you,
Gennadiy