Opensource.guide: [RFC] Getting Started > Setting Expectations

[nayafia]

Hey open source maintainers! We would love your feedback on the Getting Started > Setting expectations article. We will leave this open for comments until Sep 1, 2016.

Does anything seem inconsistent with your experience? What is missing? Are there any other helpful resources on this topic?

Feel free to comment and discuss here, or even open a pull request to suggest changes.

View | Edit

[wooorm]

This is a really cool section: :+1: I liked the fact about Bulgaria, for example. It’s got tons of useful knowledge for different levels of experience in readers.

I do think however that it’s a bit of a deep dive for beginners though, from clicking on “Get Started” in the readme, clicking past the welcome screen, and reading “So you’re interested in making your project open source”.

Maybe this is the perfect place to mention that if the reader is _not_ interested in making their project open source (at this time), they should subscribe to the mailing list (GH-41) for updates on more story lines? (GH-33) Or, a paragraph on what this guide is and isn’t, at the moment?

[MikeMcQuaid]

Really great article 👍

[lee-dohm]

I'm relatively new to open source. Even though I dipped my toes in a couple times prior to Atom, Atom is my first real foray and I've only been involved since the beginning of 2014. So my memories of my first contributions are perhaps particularly vivid. One of the things that held me back from contributing to others' projects for a time is anxiety around my code not being good enough, being out in public for scrutiny.

My concern around this section is that if I read it without having prior experiences in open source, having been mentored by others, it might make me have second thoughts around releasing a project. Having to think about all of this stuff up-front would have been intimidating for me. I think some of this is definitely more important to think about up-front than later, the name of the project for one, because changing the name after it has taken off a bit is hard. But some of the other things can wait until you've at least got something to show first, like evangelizing.

Perhaps I'm reading too much into this? I feel like we should optimize for people releasing more open source and I feel like this might be too stifling?

[gr2m]

Try to anticipate these needs beforehand so you can add them to your project from the beginning. Successful open source projects try to document as much as they can in public. Much like reusable pieces of code, reusable information means less people need to ask you the same questions over and over again. (That means less work for you!)

Maybe you can explicitly mention that documenting all your workflows is a good idea here? Usually workflows come up as the contributor base works. From my experience it’s super useful to document the workflows as soon as possible so you can point people who want contribute to it. A CONTRIBUTING.md file is a typical example

[nayafia]

@wooorm this also speaks to #22. will add something in here along those lines. thanks!

@lee-dohm see also #22. I do think there is some merit in having people think about whether they should start a new open source project, vs. finding one to contribute to. But I also wouldn't want to dissuade or scare off otherwise enthusiastic people. Maybe an additional paragraph that calls out those feelings and gives people "permission" to go through this handbook at their own pace, or to not overthink it early on, would be helpful.

[lee-dohm]

@nayafia #22 does cover the "contribute vs. create" dilemma very well. I'm more concerned about "release in the open or keep to myself" question though. I think an additional paragraph that talks about not overthinking things would be good. Especially since the reality is that only a fraction of public repos ever get contributed to. A lot of these questions can be deferred until after your first external Issue :grinning:

[nayafia]

Closed per #106.

Thank you @lee-dohm and @wooorm for your candid feedback on this section. I ended up cutting out a lot of the original text. I think it's a bit simpler and geared towards first-timers now. Thanks for making this section so much better! :heart: