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.
