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

Subject: Re: [boost] [test] Looking for co-developer/maintainer
From: Richard (legalize+jeeves_at_[hidden])
Date: 2014-05-19 18:37:33

[Please do not mail me a copy of your followup]

Bjørn Roald <bjorn_at_[hidden]> spake the secret code
<52E051FA.8030202_at_[hidden]> thusly:

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

If someone gives me SPECIFIC feedback on where my documentation needs
to be improved before it should be accepted as *the* documentation,
I'm happy to address that.

So far I haven't gotten any SPECIFIC suggestions, just vague
hand-waving that somehow these new docs aren't good enough.

Is something missing?  Name it.

Is some description confusing?  Point me to it.

Is some description incorrect?  Point me to it.

Let's not get so hung up on generalities that we hold something back
for some unspecified deficiencies, because unless we can name the
specific deficiencies, it is a pointless objection.

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

Exactly why I did a rewrite.  The structure and organization was not
useful for people who wanted to just get on with using this library.

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

Again: please point out something specific that needs documenting that
I left out.  Unless you have read both sets of docs end-to-end, you
may be assuming that something is missing when in fact it is present
and simply discussed in a different section or what have you.  I know
for a fact that there are things in my docs that have been present in
the library all along and were useful to all users but that were NOT
documented at all.

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

Again, please be specific.  This statement has been made several times
on these threads without getting to specifics.

>[...]  What I 
>had in mind is far from simply adding a new section for Richards stuff. 

I think if you do that, it will frankly be the only section that
anyone looks at.

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

Sorry, I have to laugh at some of the mind-reading that goes on in
these threads.  How does anyone besides the parties involve have any
idea how much "respect" is contained in their minds?  To my knowledge,
noone involved has made any explicit statements.

I see a problem and I do a crapton of work to fix it, but somehow I
get labelled, either implicitly or explicitly, in these threads as a
bad actor that has "no respect" for others or that I'm needing an
"attitude adjustment".

If all of you had joined in my call for reviewers many, many months ago,
you could have expressed whatever concerns you had then and made sure
that work proceeded as you thought it should.  But no, you did nothing.
You did not participate.  You come in at the last minute and basically
insult my character.  What the hell does that say about this community?

This work was not done in secret, nor in isolation.  It was explicitly
labelled as a rewrite and not an edit or evolution from the very
beginning.

The participation was open at every step of the way.  To show up at the
end and complain about how things were done doesn't earn much respect
in my eyes.
-- 
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
     The Computer Graphics Museum <http://computergraphicsmuseum.org>
         The Terminals Wiki <http://terminals.classiccmp.org>
  Legalize Adulthood! (my blog) <http://legalizeadulthood.wordpress.com>