4 ms·

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

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 10y ago
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-open-source-volunteering/ http://dirkriehle.com/publications/2014-2/the-five-stages-of...
- bad_user 10y ago
  You find a mentor even before knowing what the project does? Weird.
- twoquestions 10y ago
  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.
  - ghuntley 10y ago
    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.
    - ashitlerferad 10y ago
      If there is a FAQ it probably points to something that needs to be fixed or streamlined.
    - muraiki 10y ago
      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.
  - mastazi 10y ago
    I have to say I agree. My only question in the chat would be "where do I find the documentation outside of this chat?"
  - MaulingMonkey 10y ago
    > 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 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.
- MichaelGG 10y ago
  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 10y ago
    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 10y ago
      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 10y ago
        Sure. But ask in gitter first. You'll receive an answer suggesting you go read the README.md as it covers this info.
        Bahamut 10y ago
        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 10y ago

ghuntley 10y ago

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-open-source-volunteering/ http://dirkriehle.com/publications/2014-2/the-five-stages-of...

bad_user 10y ago
You find a mentor even before knowing what the project does? Weird.
twoquestions 10y ago
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.
- ghuntley 10y ago
  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.
  - ashitlerferad 10y ago
    If there is a FAQ it probably points to something that needs to be fixed or streamlined.
  - muraiki 10y ago
    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.
- mastazi 10y ago
  I have to say I agree. My only question in the chat would be "where do I find the documentation outside of this chat?"
- MaulingMonkey 10y ago
  > 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 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.
MichaelGG 10y ago
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 10y ago
  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 10y ago
    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 10y ago
      Sure. But ask in gitter first. You'll receive an answer suggesting you go read the README.md as it covers this info.
      - Bahamut 10y ago
        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 10y ago