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

Subject: Re: [boost] Call for Review: Boost.Test documentation rewrite
From: Rob Stewart (robertstewart_at_[hidden])
Date: 2014-01-22 04:50:59

On Jan 21, 2014, at 3:40 AM, Gennadiy Rozental <rogeeff_at_[hidden]> wrote:

> Richard <legalize+jeeves <at> mail.xmission.com> writes:
> 
>> I was told that the documentation can be updated at any time and isn't tied to a particular release, unlike features.
> 
> Usually this would be the case, but what you propose in major overhaul of  the content and structure. This is something which is bound to be disruptive 
> to existing users (even if your version is better in some aspects). The will  be people who will find something wrong with almost anything.

Your concern regarding disruption is partly valid, but if Richard's version is released now and you later link to it as the documentation of deprecated features if and when the new APIs are reviewed and accepted, it won't be so disruptive.

As for your concern about docs not pleasing everyone, while true it doesn't seem significant considering the overwhelming support for Richard's rewrite.

>> I don't understand why we can't update the documentation *now*, make things better *now*, and get on with incremental improvements after that.
> 
> Because what I have in mind is not incremental improvement over what you  propose.

That's a valid argument, but it doesn't mean releasing Richard's docs would be problematic.

>> Why can't we simply make things better immediately and then look at anything that is new?
> 
> Because I am not convinced it is better form all points of view. In fact I know it is worse from the standpoint of being boost.test library documentation: it's incomplete. And I already listed other reasons.

It's clear that many Boost developers like the new documentation and don't find it lacking. Perhaps a compromise is possible, however. Could Richard's version be released as the main documentation, with a link to your current docs in a section with an explanation that the linked docs discuss less commonly used parts of the library?

>> Why do we have to wait?
> 
> If anything needs to be released today, we can upgrade release branch to the trunk version of boost.test docs. This version addresses most of outstanding 
> issues with errors in content.

That ignores the overwhelming preference for Richard's version.

>> Forcing a delay in adopting what has already been done in 
>> order to document new features doesn't seem to benefit anyone.
> 
> Forcing users to adopt to one version only to be replaced by something else soon does not look beneficial as well.

I've addressed that here and in my reply to Richard. I don't think it's the issue you make it out to be.

___
Rob

(Sent from my portable computation engine)