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