On Friday, 19 December 2014 at 00:21:06 UTC, H. S. Teoh via
Digitalmars-d wrote:
On Thu, Dec 18, 2014 at 08:12:07PM +0000, Laeeth Isharc via
Digitalmars-d wrote:
[...]
- better reference documentation. I don't believe I lack the
ability
generally to figure things out, but the dlang.org library
reference is
far from being utterly clear if you don't start from a place of
understanding the language and its concepts. once you get the
spirit
of it, it all makes sense, but modern people don't tend to be
distinguished by their grit and many will give up first.
Please file documentation enhancement bugs in bugzilla. I do
try to
work on improving documentation when I have the time, but if
nobody
points out a possible improvement, I might never think of it
(or it
might take a long time before I notice it, esp. if I rarely use
that
module!). I'm sure others who browse bugzilla from time to time
will
also appreciate having documentation bugs to work on -- since
they're
generally the lowest-hanging fruit that even most newbies
should be able
to contribute to.
- better worked examples. python is outstanding for this.
you can
figure out how to do anything by looking at someone else's
example.
of course there isn't presently the support for this, and I
recognize
that one attracts a different kind of person when it becomes
easy to
learn a language. but such is the price of maturity.
Please file doc enhancement requests for these too. :-) A lot
of Phobos
documentation is unfortunately quite lacking in good examples.
I've done
a few of them, but generally, having a bugzilla issue for it is
much
better, because I may already know function X like the back of
my hand
and so never notice that the examples aren't that good, whereas
if a
newbie pointed out that the examples for X are unclear, then
I'd know
there's an issue and look into how to explain X better.
[...]
- finally, a bit better organisation. Andrei spoke about
needing more
lieutenants. Of course it's a no-brainer that he shouldn't be
spending his time designing a conference web site. But
perhaps you
could make it clearer by adding a section on the D wiki front
page:
"Interested in supporting D? Here's how you can help". It
could then
take you to a page that breaks down different areas to work on
and
tasks to be accomplished on each of them. Then someone with
time and
inclination can see "oh - it would be great to have someone
promote
this event on Reddit". But as things stand, I imagine to a
certain
extent nobody knows what specifically they can do.
[...]
There's some preliminary info at:
http://wiki.dlang.org/Get_involved
But it would be greatly appreciated if you could help improve
it by
adding more material. ;-)
T
In case you'll have time/will to work on this in near future -
resulted from previous "D docs suck" discussion (I'll probably do
some of it eventually, but I'm unlikely to be free till summer):
https://issues.dlang.org/show_bug.cgi?id=13863
