"Getting involved" on dlang.org?

Adam D. Ruppe via Digitalmars-d digitalmars-d at puremagic.com
Tue Dec 1 17:40:33 PST 2015


On Tuesday, 1 December 2015 at 21:01:17 UTC, Chris wrote:
> There is a lot of low hanging fruit, stuff that doesn't even 
> require coding.

You know, I just want to point out that writing documentation is 
actually really quite hard... you need to know how it works, well 
enough to write about (which can be even harder than just writing 
it yourself, especially with the complex implementations in 
Phobos) while being able to write... and still knowing what new 
readers know and don't know so your documentation is readable to 
them.

I think the reason documentation is kinda poor in so many objects 
is that it is actually really hard to do.


BTW on the topic of documentation, I actually hired a junior 
programmer with no D experience to write some D tutorials with 
me. It was actually kinda eye opening to see all the things I 
take for granted being a stumbling block for her. The first draft 
she submitted to me looks almost ridiculously simplistic to me, 
but much the stuff I write looks ridiculously complicated to 
newer users and I'm just blind to that... so I think there's a 
lot of value in getting new people to write docs, it is also just 
really hard for them to do.

It is my hope that the partnership between me and my contractor 
on this will result in something that strikes the right balance 
(and hopefully, the project will buy us a new D user too :P ) but 
it really does take a lot of time and work.


More information about the Digitalmars-d mailing list