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-21 03:40:49

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.

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

In all of this discussion did you ever even considered that my position 
might have some merit? Or anything I am saying you simply ignore?

Gennadiy