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

Subject: Re: [boost] Call for Review: Boost.Test documentation rewrite
From: Alexander Lamaison (awl03_at_[hidden])
Date: 2014-01-09 15:00:03

Gennadiy Rozental <rogeeff_at_[hidden]> writes:

> Richard <legalize+jeeves <at> mail.xmission.com> writes:
>
> Unfortunately I am very busy with moving to a new position to review this
> properly, but I feel I need to make few comments. We already kinda went
> through this couple times, so these should not be a surprise.
>
> I generally do not mind your style or tools used even though both are not my
> favorite. Here are the things that I find I am NOT ok with:
>
> 1. First and foremost: it is pretty much completely irrelevant
> Trunk version of boost.test will require us to rewrite 90% of what you did.
> 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.  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.

> 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.

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.

Alex

--
Swish - Easy SFTP for Windows Explorer (http://www.swish-sftp.org)