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.

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

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.
>
> I would like for there to be a section were people interested in working on the docs can collaborate.

I like this idea. Currently improving the docs is often blocked by the fact that only very few people for every different topic exist who know exactly what is the intended and proper behavior to be documented. And you mostly get that information only in some random bugzilla reports.

Having a common place to discuss it can be a good foundation towards solid formal spec.

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.
>
> I would like for there to be a section were people interested in working on the docs can collaborate.

Related:
http://forum.dlang.org/post/bxqyiyohbodlxypxgjal@forum.dlang.org

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.
>
> I would like for there to be a section were people interested in working on the docs can collaborate.

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.

I find the D documentation is sorely lacking in example code, and
high level descriptions of modules (thinking more of Phobos here)
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.

On 8/16/13 9:22 AM, Dicebot 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.
>>
>> I would like for there to be a section were people interested in
>> working on the docs can collaborate.
>
> I like this idea. Currently improving the docs is often blocked by the
> fact that only very few people for every different topic exist who know
> exactly what is the intended and proper behavior to be documented. And
> you mostly get that information only in some random bugzilla reports.
>
> Having a common place to discuss it can be a good foundation towards
> solid formal spec.

Just use this forum and plant e.g. [dox] in the title.

Andrei

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...

On Friday, 16 August 2013 at 16:36:16 UTC, Andrei Alexandrescu wrote:
> Just use this forum and plant e.g. [dox] in the title.
>
> Andrei

Why prefer less structured and inconvenient approach to an organized one? :) digitalmars.D is not that quite these days and discussing formal spec definitions sounds like an important goal, worth dedicated forum block.

On Friday, 16 August 2013 at 16:53:47 UTC, H. S. Teoh wrote:
>
> +1.
/snip

s/\+1/\+2/ to everything.  Might encourage me to get back to my own doc stuff.

-Wyatt

On 8/16/13 10:12 AM, Dicebot wrote:
> On Friday, 16 August 2013 at 16:36:16 UTC, Andrei Alexandrescu wrote:
>> Just use this forum and plant e.g. [dox] in the title.
>>
>> Andrei
>
> Why prefer less structured and inconvenient approach to an organized
> one? :) digitalmars.D is not that quite these days and discussing formal
> spec definitions sounds like an important goal, worth dedicated forum
> block.

The converse risk is balkanization. We already have subgroups that are effectively dead, for which similar arguments were made in the past.

Andrei

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.
>
> I would like for there to be a section were people interested in working on the docs can collaborate.

It would be perfect to get D version of http://www.dotnetperls.com/