Better docs for D (WIP)

[default0 via Digitalmars-d-announce]

On Tuesday, 5 January 2016 at 18:09:57 UTC, Andrei Alexandrescu 
wrote:
> On 01/05/2016 11:35 AM, default0 wrote:
>>
>> Yes, and because its lots of effort flowing into something 
>> that D is
>> usually very fond of: Simplicity.
>
> I'll be curious how the simplicity theme keeps when needed 
> features get added. dlang.org started very simple and grew by 
> accretion.

 From Adam's responses it would seem he is going to ignore most of 
the features the original dlang.org has in favor of focussing on 
HTML documentation.

>> I remember looking at a part of the documentation and wanting 
>> to suggest
>> a change of wording in a few sentences, since I felt like they 
>> didn't
>> convey information clear enough, but after seeing that I would 
>> have to
>> somehow best-guess my way through tons of macro syntax without 
>> clear
>> indication on where to look for explanations of anything I 
>> bailed. Not
>> about to spend half a day or a day to suggest changing three 
>> sentences
>> and be told that they were fine as is.
>
> Is the recent http://wiki.dlang.org/Contributing_to_dlang.org 
> along the lines of what you need? What other sort of 
> documentation would you find useful?

Yes, this is helpful in providing background on how to make 
changes. That said, the amount of content on this page is telling 
that it'll be an involved process to set stuff up, especially if 
at some point in my setup I get errors that are neither explained 
nor straightforward to track down. So while this is helpful, it 
also makes it clear that there's a not-low barrier to entry if I 
do want to introduce a change - which is fine, except if it's 
documentation that barrier to entry should be actually 
formulating coherent, understandable and thorough documentation 
rather than a build system.

>> Sending Adam an E-Mail is
>> something I totally would've done though :-)
>
> Again this goes back to Adam. Let's say we had a contributor 
> Eve who'd gladly take emailed questions and suggestions and 
> integrate them. Would that be as nice?
>
>
> Andrei

Much nicer than reading a somewhat long page on how to set up a 
new development environment and fiddling with it until it does 
what I want, followed by trying to guess what macros I need to 
invoke for displaying what things, followed by checking if it 
renders as expected or if I accidentally used a "," incorrectly 
somewhere instead of just formulating a documentation text that 
is hopefully an improvement over what existed prior to it (or 
filling a void that used to be there) :-)

In the end most of this comes down to a lack of motivation: I'm 
fine trying to improve documentation text if I see an issue about 
it, but if that entails stopping what I was originally doing for 
so long that I will possibly forget what I was originally doing 
(ie requires me to read documentation on how to set up a whole 
new development environment), I will usually decide that nah, it 
isn't THAT important.

While I could obviously reuse the setup after I did it once, I'm 
not keen on doing it once, I do happen to be a really lazy person 
about setting things up (not so much doing actual work on 
something that is already set up, though) because I tend to get 
really weird errors for really weird reasons when trying to (not 
in particular with D - I just always seem to be doing everything 
wrong when setting anything up).