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-05-21 17:35:52

On 05/20/2014 12:37 AM, Richard wrote:
> [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.

I don't know if anybody said they where not good enough.  For sure I 
have not.  I have just tried to express concerns about the round-about 
approach of replacing everything given that the maintainer is concerned 
that the new documentation does not cover some of the detailed 
documentation for customizing and maintaining the the library.

> Is something missing?  Name it.
>
> Is some description confusing?  Point me to it.
>
> Is some description incorrect?  Point me to it.

I have not expressed any critique of the new docs as documentation for 
the user of Boost.Test.  I see the new docs as a clear improvement and I 
hope it will be included. Or better, replace the relevant parts or all 
of the of the existing docs, whatever the maintainer find best.  I think 
your Pull Request was a good move.  It is now up to the maintainer to 
handled as it should.  If it is integrated, I hope you will continue 
your contributions.

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

Agree.

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

Agree.

>> Well, I think this statement

[[Please don't remove too much context.  It is hard to follow the 
arguments.]]

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

My reply to this would just be repeating what I have written above.

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

The quote you respond to here is not mine, nor is it critique of your docs.

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

[[The way you quote, and leave out relevant context, this discussion is 
hard to follow.]]
I take it that you are saying noting in the existing docs is worth 
keeping because nobody will ever read it.  I will certainly not stand 
behind that statement.  I would leave that up to the maintainer to decide.

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

Well, did you not just state that nobody will ever read any of the 
existing docs that the maintainer would like to keep?

> I see a problem and I do a crapton of work to fix it,

And your efforts are very appreciated

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

I take it that there is some expression of frustration in past posts, I 
think that is understandable. It just does not seem to be bringing 
anybody together to a joint effort.  So if that is desired, more care 
with what is written on the list may be a good thing.

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

Right, and I have never argued that there is anything wrong with your 
work.  The arguments have been about how to get your work properly into 
Boost.Test.  So I don't think it is relevant to what degree I have 
participated in reviews.

> You come in at the last minute and basically
> insult my character.

I hope I have not done that.  It has not been intended and if I did I 
sincerely apologize.

> What the hell does that say about this community?

I really do not know how to respond to that. I think people here try to 
do their very best to help each other.  If you interpret my words trying 
to describe what I observe as any thing else, then I am sorry for that. 
  I think you have done a very good thing working on these docs and 
offer them for integration into Boost.Test.  If your documentation for 
some reason does not make in into or replace the official Boost.Test 
docs, then I am sure there are other excellent places for it, such as in 
the tools section on the Boost web pages. If that is not satisfying, the 
alternative is a full fork which I hope it will not get to.

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

Unless I have seriously misunderstood something fundamental here, that 
does not by itself earn your documentation the right to replace 
everything in the old docs in the end.  Your assertion that that is the 
case has been the core of my concern.  I know your point of view have a 
lot of support, and I am not saying that point of view is wrong.  I just 
had the feeling there where some viable arguments made by Gennadiy and 
it is a bit beyond me why that could not be listened to, accepted and 
somehow resolved.

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

Again, I never complained about the documentation, or how it was 
created.  It is an improvement in my mind, and I have never said 
anything else.  So I do not follow your point here. Exactly what do you 
refer to when you say I "complain about how things were done"?

Thanks,
--
Bjørn