Better docs for D (WIP)

[bachmeier via Digitalmars-d-announce]

On Tuesday, 5 January 2016 at 14:18:32 UTC, Andrei Alexandrescu 
wrote:

> Overall my understanding of your message is "My system would be 
> better not for a fundamental technical reason, but because I am 
> willing to pour in it time and talent." This is the kind of 
> argument I have a lot of respect for.

IMO it's not just his willingness to put in the time that is 
different. There are some critical technical differences:

- There is one person making the decision.
- You don't have to worry about unstated (and sometimes 
arbitrary) rules. The current system feels like your dealing with 
the Soup Nazi.
- You don't have to mess with Git. For me, that's a big one, 
because I've never used Git for a large project like this.
- You don't have to build the whole website. You don't have to do 
Phobos unit tests to change a broken link.

I'll give you an example. Not by coincidence, this was the last 
contribution I attempted to make.

I read the documentation for schwartzSort, and finding that it 
conveyed no information, I wanted to suggest something better. A 
discussion forum or email message would be the ideal way to do 
so, but knowing that's not how things are done here, I decided to 
submit a PR. After at least a couple hours (it may have been 
more) looking at other documentation to find ideas for how to do 
it better, doing several revisions to get to something I found 
satisfactory, checking for no trailing spaces and making sure the 
syntax was consistent with the other documentation, battling with 
Git, and battling to get the full site to build, I submitted this:

https://github.com/D-Programming-Language/phobos/pull/3831

One person reviewed it and didn't like my change, because he felt 
the existing documentation was better. Later, someone commented 
that he liked my version. And now it's sitting there. It's not 
going to be accepted and because nobody's in charge of the 
documentation it won't be closed either.

The problem is not that my PR was (for practical purposes) 
rejected. As an academic I deal with both sides of peer review 
all the time. The problem is that I was forced to put so much 
time into it just to make a suggestion. With Adam's project, I 
can send him an email with a suggested change, and he can do as 
he wishes with it. It will take two minutes of my time.