Re: [boost] Boost.Test documentation update; alpha release

From: Peter Foley (peter_at_[hidden])
Date: 2007-08-13 08:52:10

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_at_[hidden]>
> Subject: [boost] Boost.Test documentation update; alpha release
> To: boost_at_[hidden]
> Cc: boost-users_at_[hidden], boost-docs_at_[hidden]
> Message-ID: <f9mjom$kgo$1_at_[hidden]>
> 
> 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