[twoquestions]

Somewhat echoing what spriggan3 said, it seems odd that you suggest going straight to chat to learn about a piece of software rather than trying to find answers to your questions before bothering other people. To me (and this may be a function of where I'm from), it seems very rude to ask for help with something when you don't absolutely need said help (RTFM Noob!).

It's entirely possible you meant your comment for people who already have experience with the source in question, in which case I've misunderstood you.

[ghuntley]

Let's be clear, this isn't left-pad we are talking about - these are MASSIVE projects which are in some cases 16+ years old. Personally, I find the fastest way to get up to speed is on projects of this size is to usually jump into IRC, find a mentor and start sending in documentation patches. Here the engineers for the runtime, framework, compiler teams are hanging out in Gitter and engaging with the community out in the open instead of being hidden behind closed doors. Why would you ignore an opportunity like that? They are there soliciting the advice from the community and if the there is no uptake/reciprocal energy then that's a problem. I agree on RTFM but at this stage, there is minimal documentation for the majority of these projects and that internal domain knowledge needs to be dispersed into the community. Code only tells you about the implementation, it does not tell you about the why and information about trade-offs which were made.

http://dirkriehle.com/publications/2014-2/the-five-stages-of...

[MichaelGG]

So I followed the gitter link to Orleans. I see a bunch of people talking. I'm not going to write "hey so what's this all about" so they can link me to the readme.

I went to the repo. The "homepage" includes the readme, which includes enough detail and code examples that I'm all set as far as knowing what Orlean's is "about".

[yarou]

This is how I learned Haskell. I literally went to #haskell on freenode and asked "hey so what's this all about", and many veterans of the community helped me get my feet wet.

I'm not sure what kind of toxic communities and work environments you are apart of, but if a newbie to the community can't ask questions, that's not a community that will survive or flourish in the long run.

[chris_wot]

Whilst I would never be rude to a newbie, isn't it reasonable that they at least read the FAQ, README or an I tried before asking such basic questions?

[domlebo70]

Sure. But ask in gitter first. You'll receive an answer suggesting you go read the README.md as it covers this info.

[Bahamut]

That's the type of lazy behavior that drives a lot of experienced people away from some of these chat rooms. What self-respecting developer is going to waste other people's time before doing an initial search on his/her own? That's the type of person I would rather not help because their first instinct is to waste other people's time before investing their own.

I have heard other developers call them parasites and energy vampires.

Please do not recommend this.

[MichaelGG]

I've never heard of people needing to ask where the project readme is, especially when your in a chatroom linked to the repo, which has it on the homepage.

On top of that, it's inefficient. I want a couple of paragraphs telling me what the project is about, not a conversation.

[chris_wot]

That seems... inefficient. Basically, instead of reading the readme, you suggest going to gitter to be told to read the readme?

I think I could streamline that process a bit.

[detaro]

Which you probably already could assume before, so you just wasted your AND somebody elses time. rude.

[reitanqild]

> I'm not sure what kind of toxic communities and work environments you are apart of, but if a newbie to the community can't ask questions, that's not a community that will survive or flourish in the long run.

Our definitions of toxic obviously differ a bit. I wouldn't flame anyone but (in a non paid setting of course, paying customers have the right to be wrong) I would tell them (politely) that we were there to help them when stuck, not to pull them up to speed.

Before reading this I wouldn't have believed anybody would seriously suggest that.

As others have pointed out going straight to the chat without even trying to read up on the docs first comes off as extremely entitled and lazy.

I'm maybe to hesitant, I wont bother anyone before I've read the relevant docs twice, possibly also looked quickly into the source.

[yarou]

I think a lot of people misunderstood my comment. I obviously understand that there are basic questions that can be answered by documentation.

But my point was that for any community to survive, it should be welcoming to newbies and have an environment where people shouldn't be afraid to ask questions, even if they are "dumb" by some arbitrary metric. It's also a good way to convince someone of using your particular framework, programming language, etc.

A newbie may ask why should I use X, and if experienced veterans of the community give set Y reasons to use it, I feel that's way more convincing than "RTFM scrub". It's way less elitist too.

[twoquestions]

How do you start documenting software that you don't know well? That seems like a very good way for bad documentation to get out, damaging the project.

Perhaps this is my impostor syndrome talking, but I for one would be hesitant to tempt the wrath of the Great Unseen Masters that make open source software with potentially inane questions.

[MaulingMonkey]

> That seems like a very good way for bad documentation to get out, damaging the project.

Read the code, try your best to understand it, and then get the documentation reviewed by someone who does know the software well. This works for code, too. Bonus points: Explicitly enlist feedback ("Anything I'm missing here? Any edge cases I forgot to note? Is my understanding of this correct?")

> I for one would be hesitant to tempt the wrath of the Great Unseen Masters that make open source software with potentially inane questions.

http://www.catb.org/esr/faqs/smart-questions.html

But if you're making an effort to contribute, that already counts for a lot. There might be some gruff redirection towards more effective means of contributing, if you're being a significant time sink and not helping that much, but hopefully that's a win/win in the end.

[ghuntley]

Overtime, common repetitive questions will surface in conversation. Identify these patterns, write up FAQ/documentation and submit them via the pull-request process. The Great Unseen Masters will typically be grateful and respond with dumping their brain or corrections as they would normally do so in a code review. Eventually, over time, this will build up into something they can point newbies towards to RTFM so the community does not burn out answering the same questions over and over.

[muraiki]

I think the idea is that FAQ/documentation is normally easily accessible from the repo's page, but not necessarily as obvious to find inside of gitter. I have to confess to having read all your responses but still find your linking to gitter instead of the actual repos to be bizarre.

[ashitlerferad]

If there is a FAQ it probably points to something that needs to be fixed or streamlined.

[mastazi]

I have to say I agree. My only question in the chat would be "where do I find the documentation outside of this chat?"

[bad_user]

You find a mentor even before knowing what the project does? Weird.