Better docs for D (WIP)

[Bastiaan Veelo via Digitalmars-d-announce]

On Wednesday, 30 December 2015 at 04:03:42 UTC, Andrei 
Alexandrescu wrote:
> On 12/29/2015 09:09 PM, Adam D. Ruppe wrote:
>> Putting one item per page is far more important than I even 
>> realized
>> before getting into this.
>
> We already have that:
>
> https://dlang.org/library/std/array/join.html
>
> If I search for dlang array join that the third hit on google 
> if I'm logged in, and the SECOND hit if I use an anonymous 
> session that gives google no information about my searching 
> habits. I hope you'll agree that renders the rest of your post 
> moot, for which reason I afforded to snip it.

Which is a pity, because if you had read on you would have seen 
that Adam is aware of the existence of that separate page as he 
quoted the very link above in the part you snipped.

Frankly, the fact that the Google search taken as an example here 
returns two different pages on dlang.org, with no visible clues 
whether any of them is official or experimental, is very 
confusing to me. I had to search hard to figure out if and how 
they are linked together. Turns out the one with the separate 
page is experimental, and has been so for two years now, 
according to 
https://dlang.org/library/index.html#comment-1281452140.

> Adam, there's no nice way to put what follows. You can code a 
> great deal, and I think the world of your engineering skills. 
> But there is something to be said about a bias for action at 
> the expense of strategy. I completely understand it's a lot 
> more fun to start a project than to bring it to completion, but 
> as they say in hardware, it's retired instructions that count. 
> I wish you'd consider converting some of your myriad brilliant 
> snippets into completed projects pushed into the standard 
> distribution for prime time, and also (for this case) to 
> consider strengthening the documentation tools we already have.

I greatly appreciate the energy both of you pour into D, but one 
accusing the other for not finishing projects is in this 
particular case a bit funny.

In my eyes there are three important aspects to quality 
documentation:
  1. Content
  2. Usability (legibility, X-ref, list of contents, indices, 
searching)
  3. Maintainability (ease to contribute, legibility in code, 
intuitive procedures)

The official documentation is sub-standard in 2 and 3, and Adam 
shows to be on a fast track to address these. It is a shame there 
is too much friction that this be done in the official 
documentation. But if it is too much for Adam, I am not 
encouraged to even try...

Bastiaan.