Wouldn't it make sense to have "Getting involved" on the start page of dlang.org? Most OSS projects feature something like this on their homepages. In this way, if somebody feels like contributing to D, they get the how-to info straight away (preferably not on Wiki, but on dlang.org).

There is a lot of low hanging fruit, stuff that doesn't even require coding. We should make it as easy as possible for people to get started contributing (cf. [1]). Thus, it would make sense to structure a "Getting involved" page along these lines:

1. code (Phobos, dmd etc.)
2. enhancing the documentation
3. enhancing/extending the homepage

When I started with my first humble contributions, I could only make it happen, because I got tips here on the forum (and per email). But people should be able to dive right into it, after reading "Getting involved"

Any thoughts?

[1] http://forum.dlang.org/thread/mpom8f$2eta$1@digitalmars.com

On Tuesday, 1 December 2015 at 21:01:17 UTC, Chris wrote:
> Wouldn't it make sense to have "Getting involved" on the start page of dlang.org? Most OSS projects feature something like this on their homepages. In this way, if somebody feels like contributing to D, they get the how-to info straight away (preferably not on Wiki, but on dlang.org).
>
> There is a lot of low hanging fruit, stuff that doesn't even require coding. We should make it as easy as possible for people to get started contributing (cf. [1]). Thus, it would make sense to structure a "Getting involved" page along these lines:
>
> 1. code (Phobos, dmd etc.)
> 2. enhancing the documentation
> 3. enhancing/extending the homepage
>
> When I started with my first humble contributions, I could only make it happen, because I got tips here on the forum (and per email). But people should be able to dive right into it, after reading "Getting involved"
>
> Any thoughts?
>
> [1] http://forum.dlang.org/thread/mpom8f$2eta$1@digitalmars.com

The wiki page is pretty good right now. A link to it from the home page titled "Getting Involved" would do the trick. I don't think it's a good idea to put anything more than necessary on dlang.org, because it takes an act of Congress to get it changed.

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.

On Wednesday, 2 December 2015 at 00:28:17 UTC, bachmeier wrote:
>
> The wiki page is pretty good right now. A link to it from the home page titled "Getting Involved" would do the trick. I don't think it's a good idea to put anything more than necessary on dlang.org, because it takes an act of Congress to get it changed.

If it is like an act of Congress to get it changed, there's something wrong. It shouldn't be like that.

Also, referring people to Wiki adds another layer and may look less "trustworthy". I'm talking about subjective user perception, not about the actual content on Wiki. People prefer a one-stop-shop.

On Wednesday, 2 December 2015 at 01:40:36 UTC, Adam D. Ruppe wrote:
> 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.

No, it is not easy. Even writing a good manual for a microwave is not easy. But some people are good at it and may want to contribute. Let's say there's a technical writer/reviewer who wants to add things here and there. We should make it as easy as possible for them.

Again, as I said to bachmeier (the name sounds Bavarian, btw), if the system is so complicated, there's something wrong.

Then again, simple changes like typos, fixing and adding links is not complicated at all. First start with the easy bits, and once people feel more confident, they can move on to more challenging tasks. However, the introduction and setup should be painless. I think this is very important, else we lose a lot of potential contributors.

[snip]

On Wednesday, 2 December 2015 at 01:40:36 UTC, Adam D. Ruppe wrote:
> 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.

A technique for making high quality manuals is to have a passive expert sit next to a new user and have the new user try to use the machinery and ask questions whenever there are issues. Then you repeat it with some other new users and use the recorded question-answer results to figure out what is needed for the printed manual.

On Wednesday, 2 December 2015 at 10:26:09 UTC, Chris wrote:
> Again, as I said to bachmeier (the name sounds Bavarian, btw), if the system is so complicated, there's something wrong.


yeah. I think it is a huge pain to contribute to the web site, though it is a lot better than it used to be, it still needs a bunch of setup and maintenance to keep your branches up to date. Ugh, not nice for casual users.

On Wednesday, 2 December 2015 at 15:35:23 UTC, Adam D. Ruppe wrote:
> On Wednesday, 2 December 2015 at 10:26:09 UTC, Chris wrote:
>> Again, as I said to bachmeier (the name sounds Bavarian, btw), if the system is so complicated, there's something wrong.
>
>
> yeah. I think it is a huge pain to contribute to the web site, though it is a lot better than it used to be, it still needs a bunch of setup and maintenance to keep your branches up to date. Ugh, not nice for casual users.

Setup and maintenance is one thing.

Another is having to learn Git if you don't already know it.

Another is that there is no guide for contributing to the documentation. I didn't know lines are supposed to be no more than 80 columns. I didn't know you can't have whitespace at the end of a line. I'm sure there are others that I'm not thinking about right now.

Another is that you have no way to know what is an acceptable change and what is not. Fixing a typo is no big deal. Anything more than that, it is apparently up to the person that reviews the PR. It's a big project to create a PR to suggest a change that might or might not satisfy unstated criteria.

I'm not sure what the answer might be, but contributing to the documentation is not at all the trivial process that is often claimed.

On Wednesday, 2 December 2015 at 16:22:32 UTC, bachmeier wrote:
> Setup and maintenance is one thing.
>
> Another is having to learn Git if you don't already know it.
>
> Another is that there is no guide for contributing to the documentation. I didn't know lines are supposed to be no more than 80 columns. I didn't know you can't have whitespace at the end of a line. I'm sure there are others that I'm not thinking about right now.
>
> Another is that you have no way to know what is an acceptable change and what is not. Fixing a typo is no big deal. Anything more than that, it is apparently up to the person that reviews the PR. It's a big project to create a PR to suggest a change that might or might not satisfy unstated criteria.
>
> I'm not sure what the answer might be, but contributing to the documentation is not at all the trivial process that is often claimed.

Good that we're talking about this now. Maybe the D leadership is not aware of this. Too many little annoyances that keep people from contributing.

On Wednesday, 2 December 2015 at 16:22:32 UTC, bachmeier wrote:
> Another is that there is no guide for contributing to the documentation. I didn't know lines are supposed to be no more than 80 columns.

Actually there is such documentation about it but guess what? It's hidden -like many other things which should normally be reachable:

Home Page > Resources > The D Style

Scroll down to bottom and you will see the title saying:

> Additional Requirements for Phobos
>
> Lines have a soft limit of 80 characters and a hard limit of 120 characters. This means that most lines of code should be no longer than 80 characters long but that they can exceed 80 characters when appropriate. However, they can never exceed 120 characters.