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

On 01/22/2014 10:30 PM, Alexander Lamaison wrote:

Bjørn Roald 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