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-12 16:19:18

Paul A. Bristow <pbristow <at> hetp.u-net.com> writes:
> > > >I am all for working with Richard on new docs.
> 
> You do not convince me, both from my experience trying to work on
> documentation improvement with
> you, and the list interchanges with Richard and others.

I am not quite sure what I need convince you in. From the very first time I 
reply to these threads I was open to cooperation. Here is an example:

http://thread.gmane.org/gmane.comp.lib.boost.devel/243170/focus=243336
 
> His documentation is not perfect, but it is far, far better IMO,

I respect your opinion (I might even partially agree with you), but this was 
never about how it is written, but rather what is.

> and it's what I use for everyday
> work, and I'm sure I am not the only one doing this.  So I'd like 
> to see Richard's documentation of the current release Boost.Test adopted
> now.

And I'd like to see a documentation which covers full library, not part of 
it. And the one which covers latest state of the library, not the version 
from 5 years ago.

What about next release? Do you think it is a good practice if we release 
these docs now and then something completely different half a year later?
 
> Most important, his documentation is *maintainable* by anyone with
> a plain text editor and Boost
> tools.  I see this as a key *requirement*.

This is also true with trunk docs. They are written using boostbook.

> So I believe it is unwise for its maintenance to be in the hands of 
> a single maintainer.  Boost.Test
> should be 'community maintained' by consensus.

This never work in practice. There should always be one or two people 
responsible for a library. Community can help with replies to user's 
questions, but this was always the case. 
 
> Changes to Boost.Test risk causing much trouble for many libraries, 
> so change needs to be managed better than in the past.

New modularized structure should help. And frankly - I do not believe you 
had any real issues for very long time. Especially considering that library 
is not being released.
 
> So the current Boost.Test should be frozen so that no library author 
> is suddenly forced to deal with any change to Boost.Test.

I do not think we need to do this. Maintaining backward compatibility is 
enough.
 
> Any proposed improved version, called Boost.Test2 perhaps, should 
> be subject to a FULL review of code, test, examples, and its
> documentation.  

I do not care how you call it, but we can't release 2 versions of it the 
same time. As for the review - I do not mind going through review (I 
actually would prefer it in fact), but full one might be an overkill.
 
> And it should have a small team of maintainers. 
> 
> Library authors will be free to switch to 
> Boost.Test2 (Boost.Test3...) when they find it useful and convenient.

And how one will ever know what is in every version and which one to use? Do 
we have any precedent like this in boost? I do not believe we ever had 
multiple version of, for example, filesystem library simultaneously in a 
release.
 
> Paul
> 
> PS  Boost.Test feels much more complicated than most users need.
> So we might have a Boost.MiniTest too?

I never really understood these claims, without any specific examples. I am 
obviously biased, but show me "simple" library and we can discuss it. Even 
"hidden" boost alternatives - they are not simpler from user standpoint, 
they require as much typing (if not more). They are "lighter" indeed from 
compiler standpoint, but there is a price you pay for this.

Regards,
Gennadiy