Phobos Documentation - call to action

[Zach the Mystic via Digitalmars-d]

On Wednesday, 18 March 2015 at 18:09:07 UTC, Walter Bright wrote:
> On 3/18/2015 10:55 AM, Zach the Mystic wrote:
>> No responses yet -- not that I'm any less guilty than anyone 
>> else. But maybe
>> this needs to be bumped up to a higher priority -- a hiatus on 
>> internal
>> development for a couple weeks solely to bring documentation 
>> up to a minimum.
>> Obviously clear guidelines like the ones you just posted are a 
>> plus.
>
> We have a great language, but represent it poorly in the 
> documentation. Every library entry also needs a pithy example 
> (or even any example at all), but I thought we could make 
> progress first by simply documenting what the return value is 
> supposed to be.
>
> We also need to stop pulling new library additions that have 
> obviously inadequate documentation.

I'm just thinking in terms of psychology. I haven't seen anyone 
disagree that the documentation is inadequate, so that's not even 
disputed.

But why, therefore, is it so hard to get movement on it? I 
suspect that it's because it is perceived as a chore, like 
cleaning a barn. I don't want to go in that barn by myself. But 
if I everyone's doing it, with the mutual understanding that it 
needs to get done - and no one is exempt - then it doesn't feel 
so bad.

At some point, it must be possible for documentation to get so 
bad that *nothing* is more important. Otherwise, it may well 
continue to flounder in destitute obscurity, never receiving the 
attention it deserves.