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