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