7 ms·

Announcing Open Source Guides

254 points by bkeepers 10y ago

deleted 10y ago
[deleted]
morinted 10y ago
I thought this was going to be a GitHub implementation of GitBook. Excitement fell when I clicked through. However, anything that makes getting into open source easier is good in my books.
- jdc0589 10y ago
  ditto. I was thinking it would be along the lines of Digital Ocean's curated how-to's/guides.
  - andrenotgiant 10y ago
    Ahhh that's interesting, especially because to a certain extent, people are already writing content on github organically (like this https://github.com/thewhitetulip/build-app-with-python-antitextbook https://github.com/thewhitetulip/build-app-with-python-antit...) but I always assume these are also hosted elsewhere, even if it is a github pages domain. What additional features or functionality would you want github to add to make writing/hosting guides better? Also, DigitalOcean has "contributing to open source" stuff like this https://www.digitalocean.com/community/tutorials/contributing-to-open-source-getting-started-with-git https://www.digitalocean.com/community/tutorials/contributin... and this https://www.digitalocean.com/community/tutorials/maintaining-open-source-software-projects https://www.digitalocean.com/community/tutorials/maintaining...
    - jdc0589 10y ago
      the reason the ones on digital ocean are good is because 1) reasonably consistent format, at least visually anyway. 2) curated. they actually review submissions. 3) if your guide gets accepted, you get some DO credit or something. so, there's an incentive for quality material.
rofex 10y ago
Good move. Should help newbies and fence-sitters participate more!
trengrj 10y ago
They are quite good but why do I get the feeling the domain name was bought before the idea was decided on.
- bkeepers 10y ago
  PR where domain was purchased: https://github.com/github/open-source-guide/pull/90 https://github.com/github/open-source-guide/pull/90
chuhnk 10y ago
Building a successful and sustainable long term open source project is hard. It's nice to see GitHub contributing some knowledge share that will hopefully be useful to those wishing to get started or validate what they've learned the hard way.
josh64 10y ago
This is an excellent starting resource. As one of the maintainers of a popular open source project I was wondering how I could get help with the project by attracting new contributors as I work full time and find the balancing act hard. Users have previously enquired about donations and I didn't know the best way to set up the project to accept them in a responsible manner. This guide points me in the right direction!
- joshdotsmith 10y ago
  Do you mind sending me an email sometime? You can find one in my HN profile. I'm really curious to hear about what you've done to find maintainers and how you've thought about tackling the fundraising issue.
njt 10y ago
Also check out the book "Producing Open Source Software: How to Run a Successful Free Software Project" by Karl Fogel. He just finished up the 2nd edition and made it freely available online: http://producingoss.com/ http://producingoss.com/
wimagguc 10y ago
I love the looks, the texts and just how much effort Github put into these docs. After having read quite a few pages, I'm just a bit puzzled: who are these guidelines for? Corporates usually have their own open-source guidelines (we had one at my R&D jobs even before Github existed), and these docs are a bit overdone for the tiny projects that lone devs usually put online. You know what I mean, for the ones where a single-line guideline would have been enough: "Please, if you don't want to write a readme, at least add some in-line comments".
- steveklabnik 10y ago
  > who are these guidelines for? My understanding (you'll find some of my work quoted here, and I contributed a small amount before that this was public) is that this resource is for individuals who want to be involved in open source, either as contributors or maintainers, to learn about how it works. That is, a lot of open source development is sort of a shared, "oral" history; this resource spells out a lot of things that those of us who have been in the scene for a while just know, but you have to learn at some point.
gravypod 10y ago
Ok so this is slightly off topic but I guess it still relates because it's on the this page. This document has a section on "Code of Conduct"s and it proposes this question and following answer: Q: " Why do I need a code of conduct? " A: " A code of conduct is a document that establishes expectations for behavior for your project’s participants. Adopting, and enforcing, a code of conduct can help create a positive social atmosphere for your community. " That doesn't really, for me, explain what it is or why we need one. To be fair, it follows up with this: " Codes of conduct help protect not just your participants, but yourself. If you maintain a project, you may find that unproductive attitudes from other participants can make you feel drained or unhappy about your work over time. A code of conduct empowers you to facilitate healthy, constructive community behavior. Being proactive reduces the likelihood that you, or others, will become fatigued with your project, and helps you take action when someone does something you don’t agree with. " That to me doesn't make sense. I've never really seen an enviroment that would reasonably make someone "unhappy" or "drained" by my standards nor have I ever seen a reason why someone should want to "take action when someone does something you don't agree with". I feel that if you have an open source project it's a rag-tag bag of programmers, designers, and technical people who are working on something that they should all be interested in. The discussion on the modes provided by an open source project's forums or whatever should be purely technical. When you have a purely technical medium I don't see how anyone would be upset by a convorsation. We all know what the COCs look like, I'm pretty sure we all know how they can be misued, but one thing we don't all know is why you'd need to use it in the first place (at least I don't). If you're a BDFL and you have some opinion that disagrees with another person you can just act like a human: talk it out or ignore them. I don't see why we need to, or even should, codify that. If I'm missing something please do correct me on this. PS: I just noticed some people might not understand what I mean, so I'll try to explain it with an example. I belive in freedom of speech and press. So a common expression is "I may not agree with what you have to say but I entierly support your right to say it". In Django's COC you will find this section (I'll do my best to format it): Be careful in the words that you choose. We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to: Violent threats or language directed against another person. Discriminatory jokes and language. Posting sexually explicit or violent material. Posting (or threatening to post) other people's personally identifying information ("doxing"). Personal insults, especially those using racist or sexist terms. Unwelcome sexual attention. Advocating for, or encouraging, any of the above behavior. Repeated harassment of others. In general, if someone asks you to stop, then stop. My concern is the vaugness that is nesessitated by such a controling document. Perticularly I'm afraid of the "Advocating for, or encouraging, any of the above behavior." clause. I completely belive people have the right to say all of those things. In effect I am "advocating" for the existance of speech from bad actors indirectly by saying "I may not agree with what you have to say but I entierly support your right to say it". If I advocate for ALL free speech then I must advocate for ALL free speech. Not "Free Speech*". This includes the vile behavior of bad actors whether or not I like it. Can I be banned for saying "I may not agree with what you have to say but I entierly support your right to say it"? Well as the current COC for Django stands, certiantly a case can be made for my advocacy, to some degree, of these horrible things I don't like.
ryan_lane 10y ago
This guide is really, really awesome. I maintain similar guides for companies and am excited to see a public version of most of what I've written.
- joshdotsmith 10y ago
  Do you have anything you can share at all?
EternalData 10y ago
I've been looking for something like this. It's not even the content that really matters, it's more the extra push it gives people to contribute to open source projects. I often find a lot of people don't know where to even start (myself included early on).
neom 10y ago
I've said it a billion times on HN and I'll say it a billion more, we are super fortunate to have the work that Nadia Eghbal does. If you've not read Roads and Bridges: The Unseen Labor Behind Our Digital Infrastructure I highly recommend you do [1]. Her podcast is also great [2]. [1]: http://www.fordfoundation.org/library/reports-and-studies/roads-and-bridges-the-unseen-labor-behind-our-digital-infrastructure http://www.fordfoundation.org/library/reports-and-studies/ro... [2]: https://changelog.com/rfc https://changelog.com/rfc

254 points by bkeepers 10y ago

deleted 10y ago

[deleted]

I thought this was going to be a GitHub implementation of GitBook. Excitement fell when I clicked through. However, anything that makes getting into open source easier is good in my books.

jdc0589 10y ago
ditto. I was thinking it would be along the lines of Digital Ocean's curated how-to's/guides.
- andrenotgiant 10y ago
  Ahhh that's interesting, especially because to a certain extent, people are already writing content on github organically (like this https://github.com/thewhitetulip/build-app-with-python-antitextbook https://github.com/thewhitetulip/build-app-with-python-antit...) but I always assume these are also hosted elsewhere, even if it is a github pages domain. What additional features or functionality would you want github to add to make writing/hosting guides better? Also, DigitalOcean has "contributing to open source" stuff like this https://www.digitalocean.com/community/tutorials/contributing-to-open-source-getting-started-with-git https://www.digitalocean.com/community/tutorials/contributin... and this https://www.digitalocean.com/community/tutorials/maintaining-open-source-software-projects https://www.digitalocean.com/community/tutorials/maintaining...
  - jdc0589 10y ago
    the reason the ones on digital ocean are good is because 1) reasonably consistent format, at least visually anyway. 2) curated. they actually review submissions. 3) if your guide gets accepted, you get some DO credit or something. so, there's an incentive for quality material.

rofex 10y ago

Good move. Should help newbies and fence-sitters participate more!

trengrj 10y ago

They are quite good but why do I get the feeling the domain name was bought before the idea was decided on.

bkeepers 10y ago
PR where domain was purchased: https://github.com/github/open-source-guide/pull/90 https://github.com/github/open-source-guide/pull/90

chuhnk 10y ago

Building a successful and sustainable long term open source project is hard. It's nice to see GitHub contributing some knowledge share that will hopefully be useful to those wishing to get started or validate what they've learned the hard way.

josh64 10y ago

This is an excellent starting resource. As one of the maintainers of a popular open source project I was wondering how I could get help with the project by attracting new contributors as I work full time and find the balancing act hard. Users have previously enquired about donations and I didn't know the best way to set up the project to accept them in a responsible manner. This guide points me in the right direction!

joshdotsmith 10y ago
Do you mind sending me an email sometime? You can find one in my HN profile. I'm really curious to hear about what you've done to find maintainers and how you've thought about tackling the fundraising issue.

njt 10y ago

Also check out the book "Producing Open Source Software: How to Run a Successful Free Software Project" by Karl Fogel. He just finished up the 2nd edition and made it freely available online: http://producingoss.com/ http://producingoss.com/

wimagguc 10y ago

I love the looks, the texts and just how much effort Github put into these docs. After having read quite a few pages, I'm just a bit puzzled: who are these guidelines for? Corporates usually have their own open-source guidelines (we had one at my R&D jobs even before Github existed), and these docs are a bit overdone for the tiny projects that lone devs usually put online. You know what I mean, for the ones where a single-line guideline would have been enough: "Please, if you don't want to write a readme, at least add some in-line comments".

steveklabnik 10y ago
> who are these guidelines for? My understanding (you'll find some of my work quoted here, and I contributed a small amount before that this was public) is that this resource is for individuals who want to be involved in open source, either as contributors or maintainers, to learn about how it works. That is, a lot of open source development is sort of a shared, "oral" history; this resource spells out a lot of things that those of us who have been in the scene for a while just know, but you have to learn at some point.

gravypod 10y ago

Ok so this is slightly off topic but I guess it still relates because it's on the this page. This document has a section on "Code of Conduct"s and it proposes this question and following answer: Q: " Why do I need a code of conduct? " A: " A code of conduct is a document that establishes expectations for behavior for your project’s participants. Adopting, and enforcing, a code of conduct can help create a positive social atmosphere for your community. " That doesn't really, for me, explain what it is or why we need one. To be fair, it follows up with this: " Codes of conduct help protect not just your participants, but yourself. If you maintain a project, you may find that unproductive attitudes from other participants can make you feel drained or unhappy about your work over time. A code of conduct empowers you to facilitate healthy, constructive community behavior. Being proactive reduces the likelihood that you, or others, will become fatigued with your project, and helps you take action when someone does something you don’t agree with. " That to me doesn't make sense. I've never really seen an enviroment that would reasonably make someone "unhappy" or "drained" by my standards nor have I ever seen a reason why someone should want to "take action when someone does something you don't agree with". I feel that if you have an open source project it's a rag-tag bag of programmers, designers, and technical people who are working on something that they should all be interested in. The discussion on the modes provided by an open source project's forums or whatever should be purely technical. When you have a purely technical medium I don't see how anyone would be upset by a convorsation. We all know what the COCs look like, I'm pretty sure we all know how they can be misued, but one thing we don't all know is why you'd need to use it in the first place (at least I don't). If you're a BDFL and you have some opinion that disagrees with another person you can just act like a human: talk it out or ignore them. I don't see why we need to, or even should, codify that. If I'm missing something please do correct me on this. PS: I just noticed some people might not understand what I mean, so I'll try to explain it with an example. I belive in freedom of speech and press. So a common expression is "I may not agree with what you have to say but I entierly support your right to say it". In Django's COC you will find this section (I'll do my best to format it): Be careful in the words that you choose. We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to: Violent threats or language directed against another person. Discriminatory jokes and language. Posting sexually explicit or violent material. Posting (or threatening to post) other people's personally identifying information ("doxing"). Personal insults, especially those using racist or sexist terms. Unwelcome sexual attention. Advocating for, or encouraging, any of the above behavior. Repeated harassment of others. In general, if someone asks you to stop, then stop. My concern is the vaugness that is nesessitated by such a controling document. Perticularly I'm afraid of the "Advocating for, or encouraging, any of the above behavior." clause. I completely belive people have the right to say all of those things. In effect I am "advocating" for the existance of speech from bad actors indirectly by saying "I may not agree with what you have to say but I entierly support your right to say it". If I advocate for ALL free speech then I must advocate for ALL free speech. Not "Free Speech*". This includes the vile behavior of bad actors whether or not I like it. Can I be banned for saying "I may not agree with what you have to say but I entierly support your right to say it"? Well as the current COC for Django stands, certiantly a case can be made for my advocacy, to some degree, of these horrible things I don't like.

ryan_lane 10y ago

This guide is really, really awesome. I maintain similar guides for companies and am excited to see a public version of most of what I've written.

joshdotsmith 10y ago
Do you have anything you can share at all?

EternalData 10y ago

I've been looking for something like this. It's not even the content that really matters, it's more the extra push it gives people to contribute to open source projects. I often find a lot of people don't know where to even start (myself included early on).

neom 10y ago

I've said it a billion times on HN and I'll say it a billion more, we are super fortunate to have the work that Nadia Eghbal does. If you've not read Roads and Bridges: The Unseen Labor Behind Our Digital Infrastructure I highly recommend you do [1]. Her podcast is also great [2]. [1]: http://www.fordfoundation.org/library/reports-and-studies/roads-and-bridges-the-unseen-labor-behind-our-digital-infrastructure http://www.fordfoundation.org/library/reports-and-studies/ro... [2]: https://changelog.com/rfc https://changelog.com/rfc