Better docs for D (WIP)
Adam D. Ruppe via Digitalmars-d-announce
digitalmars-d-announce at puremagic.com
Sun Jan 31 11:06:45 PST 2016
On Sunday, 31 January 2016 at 11:14:08 UTC, Rory McGuire wrote:
> If you don't get a cease and desist letter from the D
> Foundation soon I'd be surprised.
http://forum.dlang.org/post/n5sf7o$mu1$2@digitalmars.com
Andrei isn't exactly enthusiastic (though later on, he softens a
bit), but I'm convinced we need to change course anyway.
Of course, if they did try more harsh measures, I'd fight it, and
then we'd see a far more problematic division in the community.
> but you have absolutely no reason to constantly insult
> the work on the main site.
I see a distinction between insults and technical criticism. A
navigation bar that is difficult to navigate is a technical
problem - and there's a technical solution. Changing the color of
template constraints is like shoving toys under the bed when your
mother is about to inspect your room. It might fool her for about
two seconds, but she's going to see it anyway and will not be
pleased.
And more importantly, it doesn't actually clean up the dust, or
organize the toys, or discover the dirty laundry that got mixed
in to the floor.
It is an easy "solution" that you can quickly do without a lot of
work, but it isn't actually fixing anything. It is solving the
unreadable mess problem by shoving half of it under the rug
instead of actually making it readable.
(And putting the text "Constraint:" before is silly too. Anyone
who knows what that means also knows what if() means in this
context, and anybody who doesn't isn't going to learn anything
from it.)
If dlang.org fixed these problems, I'll set my site to redirect
to their site again like it used to do. But, as I've described
before, I don't think it will change in that direction without a
major, multi-faceted overhaul.
I'm doing that overhaul now. And my content changes are available
for upstream:
https://github.com/D-Programming-Language/phobos/pull/3895
Minor content so far, but lots of cross referencing, fixing
missing comments, organizing, etc.
though some of it also relies on the generator changes, so it
isn't something they can just merge and forget about...
> _Creating division in such a small community is not helpful_.
It might be such a small community because of the weakness in its
documentation. I've interviewed a LOT of new and prospective D
users over the last several months and every one of them, without
exception, expressed difficulty to me in navigating the official
site. Several of them just went elsewhere and didn't look back.
More information about the Digitalmars-d-announce
mailing list