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:


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


Reply via email to