The bad news: the Phobos documentation sux.

The good news: we can make things a lot better by just filling in blanks. For example, picking a function largely at random:

  http://dlang.org/phobos/std_uni.html#sicmp

There is no Params section, no Returns: section, and no See_Also section. Hence, I wrote a PR for it:

  https://github.com/D-Programming-Language/phobos/pull/3060

There's nothing clever about it, just filling in the blanks. If we all pitch in, we can substantially improve the documentation.

Some guidelines:

1. The sections Params, Returns, and See_Also need to be there. (Unless there are no parameters, or a void return.)

2. One PR per function being fixed.

3. Resist the urge to do more, stay focused simply on filling in the blanks, one PR per function, making things easy to review.

On Wednesday, 18 March 2015 at 03:45:07 UTC, Walter Bright wrote:
> The bad news: the Phobos documentation sux.
>
> The good news: we can make things a lot better by just filling in blanks. For example, picking a function largely at random:
>
>   http://dlang.org/phobos/std_uni.html#sicmp
>
> There is no Params section, no Returns: section, and no See_Also section. Hence, I wrote a PR for it:
>
>   https://github.com/D-Programming-Language/phobos/pull/3060
>
> There's nothing clever about it, just filling in the blanks. If we all pitch in, we can substantially improve the documentation.
>
> Some guidelines:
>
> 1. The sections Params, Returns, and See_Also need to be there. (Unless there are no parameters, or a void return.)
>
> 2. One PR per function being fixed.
>
> 3. Resist the urge to do more, stay focused simply on filling in the blanks, one PR per function, making things easy to review.

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.

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.

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.

On 3/18/15 12:42 PM, Zach the Mystic wrote:
> At some point, it must be possible for documentation to get so bad that
> *nothing* is more important.

Strategically we're definitely there, and have been for a while (if we define improving D's rate of adoption as important).

An anecdote: at work I'm making a pass through D code written by a few coworkers - all brilliant engineers. They come from various backgrounds (Python, Java, C++, Go) and it's no surprise that there's a bunch of these langauages' typical idioms redone in D. This (especially due to the Java and Go influence) makes the code very pedestrian, to the point there's no visible advantage to D over these languages. You may as well translate it to them with little trouble, and word has come about about such.

A body of examples of idiomatic uses of the language is missing. I speculate many people who take a look at D find it difficult to see (using the material we provide) how it outdoes its competition.


Andrei

On Wednesday, 18 March 2015 at 19:50:24 UTC, Andrei Alexandrescu wrote:
> On 3/18/15 12:42 PM, Zach the Mystic wrote:
>> At some point, it must be possible for documentation to get so bad that
>> *nothing* is more important.
>
> Strategically we're definitely there, and have been for a while (if we define improving D's rate of adoption as important).

Yeah, it appears so.

> A body of examples of idiomatic uses of the language is missing.

Unfortunately, I get the sense that's not the only thing that's missing.

Full disclosure: I'm not an experienced team leader, so I can't promise my suggestion will work.

That said, I suggest, for the purpose of turning motive into action, a ten-day "Documentation Holiday", akin to Franklin D. Roosevelt's "Bank Holiday" of 1933:

http://en.wikipedia.org/wiki/Emergency_Banking_Act

Guidelines for enhancements must be drawn up and made clear in advance, and the community given sufficient notice to prepare for the "holiday".

It's just an idea... but as you say, D is already there, strategically. I didn't feel great about having to be the first to respond to this thread, since I'm not a major contributor (yet, anyway) - it looks like the sign of a real problem.

On 3/18/2015 12:42 PM, Zach the Mystic wrote:
> But why, therefore, is it so hard to get movement on it?

I don't know why, so I'll ask. Why haven't you submitted a PR to fix one of them? :-)

On Wed, Mar 18, 2015 at 01:18:41PM -0700, Walter Bright via Digitalmars-d wrote:
> On 3/18/2015 12:42 PM, Zach the Mystic wrote:
> >But why, therefore, is it so hard to get movement on it?
> 
> I don't know why, so I'll ask. Why haven't you submitted a PR to fix one of them? :-)

Argh, so much hot air on the forum, so little action. This is getting so tiresome. Let's kickstart some *real* action here:

	https://github.com/D-Programming-Language/phobos/pull/3063

More will come. I'm so sick of talking about problems without doing anything, and talking about "talking about problems without doing anything" without doing anything.


T

-- 
Nothing in the world is more distasteful to a man than to take the path that leads to himself. -- Herman Hesse

On Wed, Mar 18, 2015 at 01:23:26PM -0700, H. S. Teoh via Digitalmars-d wrote:
> On Wed, Mar 18, 2015 at 01:18:41PM -0700, Walter Bright via Digitalmars-d wrote:
> > On 3/18/2015 12:42 PM, Zach the Mystic wrote:
> > >But why, therefore, is it so hard to get movement on it?
> > 
> > I don't know why, so I'll ask. Why haven't you submitted a PR to fix one of them? :-)
> 
> Argh, so much hot air on the forum, so little action. This is getting so tiresome. Let's kickstart some *real* action here:
> 
> 	https://github.com/D-Programming-Language/phobos/pull/3063
[...]

https://github.com/D-Programming-Language/phobos/pull/3064


T

-- 
MAS = Mana Ada Sistem?

On 3/18/2015 1:27 PM, H. S. Teoh via Digitalmars-d wrote:
> On Wed, Mar 18, 2015 at 01:23:26PM -0700, H. S. Teoh via Digitalmars-d wrote:
>> On Wed, Mar 18, 2015 at 01:18:41PM -0700, Walter Bright via Digitalmars-d wrote:
>>> On 3/18/2015 12:42 PM, Zach the Mystic wrote:
>>>> But why, therefore, is it so hard to get movement on it?
>>>
>>> I don't know why, so I'll ask. Why haven't you submitted a PR to fix
>>> one of them? :-)
>>
>> Argh, so much hot air on the forum, so little action. This is getting so
>> tiresome. Let's kickstart some *real* action here:
>>
>> 	https://github.com/D-Programming-Language/phobos/pull/3063
> [...]
>
> https://github.com/D-Programming-Language/phobos/pull/3064

You da man, H.S. !