Worst Phobos documentation evar!

[Andrei Alexandrescu via Digitalmars-d]

On 12/30/14 1:00 PM, ketmar via Digitalmars-d wrote:
> On Tue, 30 Dec 2014 12:26:52 -0800
> Walter Bright via Digitalmars-d <digitalmars-d at puremagic.com> wrote:
>
>> On 12/30/2014 11:49 AM, Andrei Alexandrescu wrote:
>>> On 12/30/14 11:47 AM, Adam D. Ruppe wrote:
>>>> On Tuesday, 30 December 2014 at 18:44:15 UTC, ketmar via Digitalmars-d
>>>> wrote:
>>>>> but the unnecessary noisy (and badly documented, that's it)
>>>>> documentation language surely doesn't add any joy for documentation
>>>>> writer.
>>>>
>>>> Yeah, I see that too; I complain about ddoc as well (though I generally
>>>> like it, I just wish it encoded the output correctly and had some nicer
>>>> defaults, but I don't care enough to fight over it) but I don't think it
>>>> is that big of a block because the hard part is writing the text rather
>>>> than the formatting.
>>>
>>> Agreed! -- Andrei
>>>
>>
>> I agree so strongly that just email me the freakin' text and I'll mark it up and
>> submit it. Ketmar, I expect my email inbox to fill up promptly! :-)
>
> i'm sux in writing documentation. i'm always explaining the things that
> are perfectly clear for everyone and failed to explain the things that
> are not so obvious ('cause they are obvious to me ;-). so i doubt that
> it even pass spamcheck.
>
> besides, if i start to do some real work, i will not have enough time
> to write my rants here!

I'm choosing to reply to this because it is a perfect example of a 
pattern of cognitive dissonance that I've witnessed before in this 
forum. The irony is so astonishing, you were entirely right to frame it 
humorously - although it's not funny because it's entirely true: there's 
no time to get stuff done - it's all sucked by hand-wringing over it.

You must be spending literally hours a week reading and composing 
messages on this forum, and my perception is that you are truly willing 
and able to help move D forward. Your posts are eloquent and well 
written. Yet when it comes to actually doing it, well, that's what 
doesn't quite happen.

It seems to me that for some of us, contributing to D is like teenage 
sex: everybody talks about it, everybody knows how it should be done 
better than all others, but few are actually doing it.

My question is how we can break this pattern? What steps can the D 
leadership take to convince folks like you to actually add, even with 
the simplest things?


Andrei