www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - "Getting involved" on dlang.org?

reply Chris <wendlec tcd.ie> writes:
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
Dec 01 2015
next sibling parent reply bachmeier <no spam.net> writes:
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.
Dec 01 2015
parent Chris <wendlec tcd.ie> writes:
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.
Dec 02 2015
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
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.
Dec 01 2015
next sibling parent reply Chris <wendlec tcd.ie> writes:
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]
Dec 02 2015
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
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.
Dec 02 2015
parent reply bachmeier <no spam.com> writes:
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.
Dec 02 2015
next sibling parent reply Chris <wendlec tcd.ie> writes:
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.
Dec 02 2015
parent reply bachmeier <no spam.com> writes:
On Wednesday, 2 December 2015 at 16:54:56 UTC, Chris wrote:
 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.
I'm going to guess that they are probably not aware of it. When you are the one that makes the rules, you don't face any of the issues that follow from not knowing the rules. And if you are a core developer, there's no problem with assuming that Git/Github usage is trivial. The important question is what we are going to do about it. A starting point would be to state the rules: This is the style you have to use. This is what you can and cannot assume the reader knows. This is what examples should and should not look like. This is what See_Also is for. And so on. Of course, I can't write the document, or else I wouldn't need it.
Dec 02 2015
next sibling parent bachmeier <no spam.com> writes:
On Wednesday, 2 December 2015 at 21:22:43 UTC, bachmeier wrote:
 On Wednesday, 2 December 2015 at 16:54:56 UTC, Chris wrote:
 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.
I'm going to guess that they are probably not aware of it. When you are the one that makes the rules, you don't face any of the issues that follow from not knowing the rules. And if you are a core developer, there's no problem with assuming that Git/Github usage is trivial. The important question is what we are going to do about it. A starting point would be to state the rules: This is the style you have to use. This is what you can and cannot assume the reader knows. This is what examples should and should not look like. This is what See_Also is for. And so on. Of course, I can't write the document, or else I wouldn't need it.
Oh, and one more: someone should be able to say, "This is what I'd like to do with the documentation for this function. What do you think?" I have no plan to create a PR unless I expect it to be accepted.
Dec 02 2015
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/02/2015 04:22 PM, bachmeier wrote:
 On Wednesday, 2 December 2015 at 16:54:56 UTC, Chris wrote:
 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.
I'm going to guess that they are probably not aware of it.
There is awareness. Good documentation is something we know we need and is an ideal to live into. Problem is prioritizing. I must be spending cumulatively a couple of hours everyday just deciding what to work on next. Forty-six emails are waiting in my Inbox, earliest from September; most likely their senders either have long forgotten about them, or are wondering about my manners. But each is nontrivial. Some are one mini-project each, and some are major projects in themselves. There are occasional mini-fires on the forum, and literally I could fill every day with work suggested on the forum. I'm trying to delegate as best I can. As is widely known around here, that works only sometimes, and sadly not always things are done the way I'd wish are. At the same time my mind is burning at both ends with work on the containers. Which are going to be awesome. There's so much going on, I find myself scheming and running calculations first time I open eyes in the morning (actually even before :o)) and last time before I fall asleep. In this context, it's very difficult for me to think, "Sure, the best work of my life can wait. Now let me sit down and write a good tutorial." I thought dedicating my time to D will make things much easier - but in fact the added focus and productivity only piles more things on the plate! Andrei
Dec 02 2015
parent Chris <wendlec tcd.ie> writes:
On Wednesday, 2 December 2015 at 21:46:39 UTC, Andrei 
Alexandrescu wrote:
 There is awareness. Good documentation is something we know we 
 need and is an ideal to live into.

 Problem is prioritizing. I must be spending cumulatively a 
 couple of hours everyday just deciding what to work on next. 
 Forty-six emails are waiting in my Inbox, earliest from 
 September; most likely their senders either have long forgotten 
 about them, or are wondering about my manners. But each is 
 nontrivial. Some are one mini-project each, and some are major 
 projects in themselves.

 There are occasional mini-fires on the forum, and literally I 
 could fill every day with work suggested on the forum. I'm 
 trying to delegate as best I can. As is widely known around 
 here, that works only sometimes, and sadly not always things 
 are done the way I'd wish are.

 At the same time my mind is burning at both ends with work on 
 the containers. Which are going to be awesome. There's so much 
 going on, I find myself scheming and running calculations first 
 time I open eyes in the morning (actually even before :o)) and 
 last time before I fall asleep.

 In this context, it's very difficult for me to think, "Sure, 
 the best work of my life can wait. Now let me sit down and 
 write a good tutorial."

 I thought dedicating my time to D will make things much easier 
 - but in fact the added focus and productivity only piles more 
 things on the plate!


 Andrei
This goes without saying. Nobody in the community expects you or Walter to write a tutorial how to contribute to D. The points made here refer to the fact that every so often you post a thread asking people to contribute and mention the documentation among other things. However, it's not really easy to get involved, because information is hidden - "Getting involved" is not even on the front page - and while there are steps that describe how to pull and push with git, there are some steps in between that are not 100% clear due to git not being the friendliest tool to work with, and github adds yet another layer of complexity. What needs to be added are tips & tricks along with typical pitfalls and common mistakes (cf. bachmeier's post). Many people have mentioned that they _would_ contribute, if it didn't take them hours of trial and error to get things working (even long standing contributors have said that it can be quite nasty at times). I think the lack of action on the side of the community can be attributed in parts to the relatively high entry threshold for even trivial changes. On a lighter note, I know how it feels when you think about a project when you go to bed, and again before you even open your eyes in the morning. I find that it helps _not_ to think about these things too hard when you're "off" (whatever that means in your case). Personally, I have better ideas, when I detach myself from a project, do something else and come back with a fresh head. But everyone is different. I don't know what works for you.
Dec 03 2015
prev sibling parent bachmeier <no spam.com> writes:
On Wednesday, 2 December 2015 at 21:45:55 UTC, Andrei 
Alexandrescu wrote:
 On 12/02/2015 04:22 PM, bachmeier wrote:
 On Wednesday, 2 December 2015 at 16:54:56 UTC, Chris wrote:
 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.
I'm going to guess that they are probably not aware of it.
There is awareness. Good documentation is something we know we need and is an ideal to live into. Problem is prioritizing. I must be spending cumulatively a couple of times everyday just deciding what to work on next. Forty-six emails are waiting in my Inbox, earliest from September; most likely their senders either have long forgotten about them, or are wondering about my manners. But each is nontrivial. Some are one mini-project each, and some are major projects in themselves. There are occasional mini-fires on the forum, and literally I could fill every day with work suggested on the forum. I'm trying to delegate as best I can. As is widely known around here, that works only sometimes, and sadly not always things are done the way I'd wish are. At the same time my mind is burning at both ends with work on the containers. Which are going to be awesome. There's so much going on, I find myself scheming and running calculations first time I open eyes in the morning (actually even before :o)) and last time before I fall asleep. In this context, it's very difficult for me to think, "Sure, the best work of my life can wait. Now let me sit down and write a good tutorial." I thought dedicating my time to D will make things much easier - but in fact the added focus and productivity only piles more things on the plate! Andrei
When I refer to the leadership, I'm thinking of the core dev team. This is not something you or Walter should be messing with. The D community is large enough at this point that others should be able to take care of these things without you even knowing about it. Maybe that won't happen, but we're doomed if the two of you are writing a guide for contributing to the documentation.
Dec 02 2015
prev sibling parent reply NX <nightmarex1337 hotmail.com> writes:
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.
Dec 02 2015
parent Chris <wendlec tcd.ie> writes:
On Wednesday, 2 December 2015 at 19:06:05 UTC, NX wrote:
 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.
That's not good enough.
Dec 02 2015
prev sibling parent Ola Fosheim =?UTF-8?B?R3LDuHN0YWQ=?= writes:
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.
Dec 02 2015