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.

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.

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.

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

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.

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.