Re: [boost] Call for Review: Boost.Test documentation rewrite

Subject: Re: [boost] Call for Review: Boost.Test documentation rewrite
From: Gennadiy Rozental (rogeeff_at_[hidden])
Date: 2014-01-10 10:45:24

Alexander Lamaison <awl03 <at> doc.ic.ac.uk> writes:

> > I keep asking you to collaborate on something which we 
> > can actually release.
> > I am not sure why you keep ignoring me.

> Richard didn't ignore you.  He explained that he documented the version
> of Boost.Test that users are actually using.  The version that ends up
> in the releases.  

The new version that needs to be releases IS the one that will appear in a 
release and the one which is significantly different.

> > It's no use to the users if the documentation
> describes what may happen at some unspecified point in the future, but
> doesn't match the code in front of them.

It is not some unspecified time in a future. New version is ready and just 
need to be fitted with new documentation.
 
> > 2. This is not a Boost.Test documentation - this is is boost unit test
> > framework documentation
> >
> > You are missing the whole original point of layering in boost.test 
design.
> > You are missing description of all the other independent layers. In 
general
> > I think you are missing quite a few other things as well.
> 
> The problem with the original documentation was that so much of it was
> about how the UTF was implemented.  No-one cares.  Users only want to
> know how to use it to write unit test with Boost.Test.  Back in the day
> I had to learn that from Richard's blog.

You can probably have number of complains about existing implementation. 
This is NOT one of them. If anything it was lacking reference part and 
Richard's version improve on that. Would you care to show an example?
 
> I could respond to each of your criticism but I think I'll just end by
> saying that, if a team have scrutinised this documentation for months,
> finding it greatly improved, and the user reception is overwhelmingly
> positive, perhaps Richard has some skills in the documentation area.

I am not argue his skills. I just want to apply them in a right direction.

Gennadiy