Re: [boost] [test] Looking for co-developer/maintainer

Subject: Re: [boost] [test] Looking for co-developer/maintainer
From: Bjørn Roald (bjorn_at_[hidden])
Date: 2014-01-22 18:19:22

On 01/22/2014 10:30 PM, Alexander Lamaison wrote:
> Bjørn Roald <bjorn_at_[hidden]> writes:
>
>> As far as the documentation, I find it hard to understand why the
>> various views on the Library that Richards documentation and the
>> original documentation represent could not be integrated somehow to a
>> better total.  However if the attitude is that we have new docs, get
>> rid of the old.  Anybody see a pattern here?  I have very little
>> understanding of how that should work to the better of Boost.
>
> A lot of the old documentation is not useful for Boost.Test users, and
> it swaps the bits that are useful.  For example, the first two chapters
> are about the execution monitor and the program execution monitor, two
> details that the Boost.Test users never need to know about.  Users have
> to read to Part IV before they find out how to use the library in the
> recommended manner.

Sure, I do agree with you that these are problems with the current 
documentation from the view-point of a typical library user.  I have 
been struggling with this myself almost every time I have refereed to 
the docs for simple advise of setting up some ad-hock tests for a 
project.  That does not mean that there are not other view-points or 
aspects of Boost.Test that deserve documentation.  The key issue for 
improvement is that the resulting documentation need to be clear about 
which sections are the more useful to "just" get started using 
Boost.Test, so the average developer that are just trying use Boost.Test 
will simply skip less interesting parts, or simply not get there as it 
is deep in some reference section, or documentation for maintenance and 
design of the library itself.  Some structural change is needed to make 
these sort of aspects very explicit and clear if any sort of combination 
of the docs are to be useful.

> Once you cut it down to size, you would result in what Richard has
> written, albeit, less clearly worded.

Well, I think this statement is very heavy biased on the view that no 
other aspect of Boost.Test than those that has concerned Richard are the 
worth documenting.  If that where a global and final truth, then it 
would be a valid assertion, but it is not.

> That's why combining the two
> would not be better: a major benefit of Richard's is the _absence_ of
>documentation.

Yes shorter is in general better, no doubt. But, to be true, that 
assumes the shorter version provide the same or at least a sound level 
of information completeness.  Removing potentially useful information in 
the name of brevity may be a very bad idea. By the way, I am not simply 
suggesting that to combine the available docs would improve anything.  I 
was suggesting the various views could be integrated somehow.  What I 
had in mind is far from simply adding a new section for Richards stuff. 
  As it stands, without some adjustments in the attitudes of the major 
stakeholders here with regards to each other's work, I see little hope 
of this happening.  That is a sad thing as I think their combined effort 
and respect could have led to much more than two competing efforts is 
likely to ever do.

-- 
Bjørn