Better docs for D (WIP)

[Rory McGuire via Digitalmars-d-announce]

On Sun, Jan 31, 2016 at 9:06 PM, Adam D. Ruppe via
Digitalmars-d-announce <digitalmars-d-announce at puremagic.com> wrote:
> 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.

100% bro, I'm not referring to making a separate implementation or
anything like that I'm saying: "As a 'important user' in our community
your voice counts for something and be careful what you say".

Surely everyone can agree on that?