Can we get a forum section devoted to documentation?

[H. S. Teoh]

On Fri, Aug 16, 2013 at 06:29:40PM +0200, Craig Dillabaugh wrote:
> On Friday, 16 August 2013 at 16:07:59 UTC, Andre Artus wrote:
> >I would like to contribute to the D ecosystem, but as I'm still in
> >the learning process I do not want to get my sticky fingers all
> >over someones nice clean code.
> >
> >I have poured over the documentation and see that there are a few
> >low-hanging fruit that I would like to pluck. So I have decided to
> >do so.

+1.


> >I would like for there to be a section were people interested in
> >working on the docs can collaborate.

+1. I would subscribe to that.


> It is pretty easy to make minor corrections to the documentation
> through the GitHub repo. I made such a correction myself to a
> glaring documentation error recently.  My first ever open source
> contribution, but hopefully many more to come in the future.  I
> often thought, like yourself, that improving the D documentation
> would be a good way to contribute.  Having a forum to vet ideas
> would be very nice.

We badly, badly, need people to work on the documentation. One of the
major complaints I heard from a friend about D is that the docs are very
poor.

Coders tend to be very bad at writing docs, because we understand our
own code too well -- our perception is unconsciously colored by hidden
assumptions that newbies don't know about, which makes the docs hard to
understand. Writing docs for others' code is better, though. :)


> I find the D documentation is sorely lacking in example code,

+1. I think *every* Phobos function needs at least one code example, at
least in principle. It may sound redundant to experienced D coders, but
such redundancy is very important for somebody who's learning the
language for the first time.


> and high level descriptions of modules (thinking more of Phobos here)

Most Phobos modules suffer from this problem. The first paragraph often
just says something to the effect of "this is module X (we already know
that) and it contains Y, Z, W (we can see that already)". Very
unhelpful. We need descriptions of:

1) What: what this module does -- from the high-level view.

2) Why: why do we need this module in the first place? why should we
care?

3) When: when this module might be useful. Give some example
applications that might benefit from this module.

4) How: example code to demonstrate how this module can help you in your
code.

5) Where: overview of module contents (or, where to find stuff). A lot
of Phobos docs currently just dump a long unnavigable list of symbols
declared, with no high-level organization of them. This makes it nigh
impossible to find what you're looking for unless you already know where
it is. We should at least group things into logical sections /
categories, and put these categories near the top where it's easier to
find what you're looking for (std.range, while not perfect, is a good
example of how this can help navigate the module).


> and having a forum to say "Here is some 'description/example code' I
> want to add to the Phobos docs", would be a good way for less
> experienced developers to start contributing. Such a forum would be a
> good way to get some feedback before getting to the point of pushing
> your changes to the Repo.

+1. You can also just submit pull requests to update the docs; it's a
good way to get feedback from the core Phobos devs.

A large number of Phobos modules badly need a documentation facelift.
I've tried to improve std.range before -- I can't say it's perfect but
it's certainly a lot better than what it used to be. But too many Phobos
modules aren't even at that level yet. We really need to fix that if we
want wider adoption of D.

Also needed is somebody to read through related parts of the docs, and
catch contradictory parts (e.g., the terminology confusion between
http://dlang.org/tuple.html, http://dlang.org/phobos/std_typecons.html,
and http://dlang.org/phobos/std_typetuple.html).

In any case, I think I talk too much about it. Let's get the
documentation pull requests going!! And start the docs discussion group.


T

-- 
The early bird gets the worm. Moral: ewww...