7 ms·

Non-Code Contributions to Open Source (2021)

67 points by asicsp 4y ago

stared 4y ago
I think the most vastly needed contribution to open-source is writing, fixing, and polishing the README.md file. Or at least one with the Often the newcomers are the best ones to do so, as they see things that are "obvious" for the maintainers but not necessary for anyone starting. It includes installation options (and what to do when seeing common errors), typical use cases, and links to further materials.
- ethbr0 4y ago
  I worked at a (non-tech) company that had internal org-wide code visibility + a strong culture of README always documenting "How do I run this?" It was a godsend and game changer for quickly finding reusable code and understanding how it did what it did. There were some key enablers (well-designed permissions request system, mature EDW), but at the end of the day it was people taking the time. Since then I've always tried to be that person -- if someone who knows nothing about the project can't get it running on a reasonably standard system by following the steps in the README, then the README isn't finished.
ctrlmeta 4y ago
Very good list. As an open source user, I want to add that I look for two types of writings when I am trying to use a new open source project. The first type has official tutorials (not full reference, not API docs, but official tutorials). It helps me to learn how the project authors/maintainers want me to use the software. The second type has blog posts and articles written by other users of the project. These are unofficial, informal posts that shows how the software is used by other people. They help me to learn alternate ways of using the software, learn what problems others faced and how they solved it. Any contribution in these two types of documentations are sure to make good impact on a good number of users.
antirez 4y ago
Documentation one of the most important part of a software project. It must provide a clear and coincise representation of the behavior of the system and should be written by the most expert developers and designers of the software project. Only then the documentation can be good, and at the same time, in the process of writing, inform the developers of semantical inconsistencies present in the system: because describing a system is debugging and auditing it at a very deep level. Inconsistent systems can't be clearly described.
setgree 4y ago
In my experience, the Ethereum foundation is very open to pull requests on its documentation. It helps that they’ve got a style guide for resolving potential disputes: https://ethereum.org/en/contributing/style-guide/ https://ethereum.org/en/contributing/style-guide/
gorilla0 4y ago
Agree, people probably underestimate the value of documentation. For example, Michael Kerrisk the well-known author of the book The Linux Programming Interface is the maintainer of the man-pages project and has probably has more contributions via documentation rather than actual code.
marcodiego 4y ago
Simply being a user is a form of helping FLOSS. It helps to weaken the argument "nobody uses that".
jjzhiyuan 4y ago
"Helping Newcomers" onboarding is also a very important contribution to open source community!
- MayeulC 4y ago
  Yes. I like idling in Q/A channels (mostly IRC or Matrix) to handle support requests or answer questions from time to time. Even if I'm not a core dev or even a seasoned user, I can often help debug, point to the documentation, or ping relevant people/forward to proper channels.
pkz 4y ago
This! Many seem to think that only developers can contribute in a way that gains experience and CV-items. UX people, designers and wordsmiths can have a great impact on a project too. I wish more people found out and contributed.
bawolff 4y ago
> Tip: Most people look for well-written and up-to-date tutorials instead of documentation. Is that true? I doubt it. Most people try to google their current question,not read a long form tutorial. Edit: fair enough on the hello world tutorial, i like those too. I was thinking more like linux HOWTO style tutorials.
- Retr0id 4y ago
  Personally, I look for the MVP usage example - something equivalent to a "hello world". If that's provided by the docs, excellent, that's what I read first. Once I understand the gist of things, I can drill down into more specific documentation. However, a lot of "documentation" is just a list of descriptions for each function in a library (for example). This is great once you're up to speed, but it makes it hard to get an overall impression of how it works and how to use it. In these cases, I tend to find myself reading somebody's blog post for my initial introduction.
  - sudo_navendu 4y ago
    It is the same for me. A tutorial to get me started and then docs once I'm comfortable using it.
Timwi 4y ago
I definitely agree with the sentiment, but I think project maintainers need to see this post more than users do. I've been a user for a long time (I didn't just turn on a computer for the first time in my life). I see issues with software everywhere and I'm the kind of person that itches to report them so that they can be fixed/improved. The article seems to imply that people like this are rare and people need a push to become like this. But the reality is that reporting bugs is rarely done because it is often not welcome. UX issues even more so. Developers look down on this as a nuisance rather than a contribution. It sometimes leads to unnecessary debates, even flame wars, that quickly stray from the subject of the actual bug reported. Even when it doesn't, the best case scenario is often that it's just ignored. You post your bug into some issue tracker and it just sits there and nobody cares. It's like talking to the proverbial wall. If you want the types of contributions listed in this article in your project, you need to welcome them. You need to thank users, you need to act on them, and you need the developers to stay on focus.
- calvinmorrison 4y ago
  My findings is that there should be a very low bar for opening bugs. Maybe don't call them bugs, call them 'tips'. No, I am not going to spend 10 minutes filling out this report, or sign up for github to do so, but I would be happy to send a brief message describing my issue. You're probably just going to close it in 3 weeks automatically anyway. Running off this new HN phrase about non-zero amounts of fraud - There's a non-zero amount of 'bad' bug reports and many good reports are left to the wayside because of this.
  - bawolff 4y ago
    In commercial world there are whole teams of people to filter reports as not to distract devs from their jobs. In the open source world, bad bug reports really are a drain with negative value. Someone has to read them at the end of the day. Nobody expects the amount to be 0%, but at the same time nobody has time for 200 mysterious reports of "i did something unspecified, and it did something i didnt expect, but im not going to tell you what it did, what i thought it should do, or what version im running"
  - 4y ago
prego_xo 4y ago
This is probably the clearest explanation of exactly what users can do to (non-mentarily) support an open-source project that I have seen to date.
ternaus 4y ago
I would add to the list - donations. I am core developer of https://albumentations.ai/ https://albumentations.ai/ We have web site, documentation, tutorials, blog posts. It is not perfect, and could be improved but people use the library. Metrics: 10k stars at GitHub, 11k downloads per day https://pypistats.org/packages/albumentations https://pypistats.org/packages/albumentations We have 100s of bug reports / feature requests and someone needs to go through this. Even when someone picks a feature, writes code and creates pull request, core team member needs go through it, and typically there are a few iterations before the PR is merged. In our case we would like to hire full time engineer to do all this stuff. But it is money. => donations may help more than advice from the blog post, although I agree with every word in it.
euroderf 4y ago
When the subject is documentation, I wonder whether the "docs as code" approach can make documentation both more findable and more easily contributable-to. Put the (Markdown) docu for Foo in the same directory as Foo itself, making it super easy to keep the Foo docu up to date... while leaving it to a project meister to pull these somewhat scattered info-items (for the myriad values of Foo) into final user docu.
atoav 4y ago
As a programmer who studied philosophy and worked as a freelance graphic designer I often contribute in terms of writing, clarifying, creating explainer graphics, logos, splash screens etc. The issue with all of these fields is, that there is a ton of personal taste involved. As a professional I know how to push my taste aside and create something that serves a project — but not every contributor who will contribute e.g. graphics will be able to maintain that distance. This can potentially lead to emotionally exhaustive situations, where a maintainer or community is thankful for a contribution, but they have to say "no thanks" because the graphics/text don't fit the standard of the project. Same thing goes for well meant "analysis" where contributers ignored all existing issues and discussion — nice of you to do that, but consider that ot also creates work.

67 points by asicsp 4y ago

I think the most vastly needed contribution to open-source is writing, fixing, and polishing the README.md file. Or at least one with the Often the newcomers are the best ones to do so, as they see things that are "obvious" for the maintainers but not necessary for anyone starting. It includes installation options (and what to do when seeing common errors), typical use cases, and links to further materials.

ethbr0 4y ago
I worked at a (non-tech) company that had internal org-wide code visibility + a strong culture of README always documenting "How do I run this?" It was a godsend and game changer for quickly finding reusable code and understanding how it did what it did. There were some key enablers (well-designed permissions request system, mature EDW), but at the end of the day it was people taking the time. Since then I've always tried to be that person -- if someone who knows nothing about the project can't get it running on a reasonably standard system by following the steps in the README, then the README isn't finished.

ctrlmeta 4y ago

Very good list. As an open source user, I want to add that I look for two types of writings when I am trying to use a new open source project. The first type has official tutorials (not full reference, not API docs, but official tutorials). It helps me to learn how the project authors/maintainers want me to use the software. The second type has blog posts and articles written by other users of the project. These are unofficial, informal posts that shows how the software is used by other people. They help me to learn alternate ways of using the software, learn what problems others faced and how they solved it. Any contribution in these two types of documentations are sure to make good impact on a good number of users.

antirez 4y ago

Documentation one of the most important part of a software project. It must provide a clear and coincise representation of the behavior of the system and should be written by the most expert developers and designers of the software project. Only then the documentation can be good, and at the same time, in the process of writing, inform the developers of semantical inconsistencies present in the system: because describing a system is debugging and auditing it at a very deep level. Inconsistent systems can't be clearly described.

setgree 4y ago

In my experience, the Ethereum foundation is very open to pull requests on its documentation. It helps that they’ve got a style guide for resolving potential disputes: https://ethereum.org/en/contributing/style-guide/ https://ethereum.org/en/contributing/style-guide/

gorilla0 4y ago

Agree, people probably underestimate the value of documentation. For example, Michael Kerrisk the well-known author of the book The Linux Programming Interface is the maintainer of the man-pages project and has probably has more contributions via documentation rather than actual code.

marcodiego 4y ago

Simply being a user is a form of helping FLOSS. It helps to weaken the argument "nobody uses that".

jjzhiyuan 4y ago

"Helping Newcomers" onboarding is also a very important contribution to open source community!

MayeulC 4y ago
Yes. I like idling in Q/A channels (mostly IRC or Matrix) to handle support requests or answer questions from time to time. Even if I'm not a core dev or even a seasoned user, I can often help debug, point to the documentation, or ping relevant people/forward to proper channels.

pkz 4y ago

This! Many seem to think that only developers can contribute in a way that gains experience and CV-items. UX people, designers and wordsmiths can have a great impact on a project too. I wish more people found out and contributed.

bawolff 4y ago

> Tip: Most people look for well-written and up-to-date tutorials instead of documentation. Is that true? I doubt it. Most people try to google their current question,not read a long form tutorial. Edit: fair enough on the hello world tutorial, i like those too. I was thinking more like linux HOWTO style tutorials.

Retr0id 4y ago
Personally, I look for the MVP usage example - something equivalent to a "hello world". If that's provided by the docs, excellent, that's what I read first. Once I understand the gist of things, I can drill down into more specific documentation. However, a lot of "documentation" is just a list of descriptions for each function in a library (for example). This is great once you're up to speed, but it makes it hard to get an overall impression of how it works and how to use it. In these cases, I tend to find myself reading somebody's blog post for my initial introduction.
- sudo_navendu 4y ago
  It is the same for me. A tutorial to get me started and then docs once I'm comfortable using it.

Timwi 4y ago

I definitely agree with the sentiment, but I think project maintainers need to see this post more than users do. I've been a user for a long time (I didn't just turn on a computer for the first time in my life). I see issues with software everywhere and I'm the kind of person that itches to report them so that they can be fixed/improved. The article seems to imply that people like this are rare and people need a push to become like this. But the reality is that reporting bugs is rarely done because it is often not welcome. UX issues even more so. Developers look down on this as a nuisance rather than a contribution. It sometimes leads to unnecessary debates, even flame wars, that quickly stray from the subject of the actual bug reported. Even when it doesn't, the best case scenario is often that it's just ignored. You post your bug into some issue tracker and it just sits there and nobody cares. It's like talking to the proverbial wall. If you want the types of contributions listed in this article in your project, you need to welcome them. You need to thank users, you need to act on them, and you need the developers to stay on focus.

calvinmorrison 4y ago
My findings is that there should be a very low bar for opening bugs. Maybe don't call them bugs, call them 'tips'. No, I am not going to spend 10 minutes filling out this report, or sign up for github to do so, but I would be happy to send a brief message describing my issue. You're probably just going to close it in 3 weeks automatically anyway. Running off this new HN phrase about non-zero amounts of fraud - There's a non-zero amount of 'bad' bug reports and many good reports are left to the wayside because of this.
- bawolff 4y ago
  In commercial world there are whole teams of people to filter reports as not to distract devs from their jobs. In the open source world, bad bug reports really are a drain with negative value. Someone has to read them at the end of the day. Nobody expects the amount to be 0%, but at the same time nobody has time for 200 mysterious reports of "i did something unspecified, and it did something i didnt expect, but im not going to tell you what it did, what i thought it should do, or what version im running"
- 4y ago

prego_xo 4y ago

This is probably the clearest explanation of exactly what users can do to (non-mentarily) support an open-source project that I have seen to date.

ternaus 4y ago

I would add to the list - donations. I am core developer of https://albumentations.ai/ https://albumentations.ai/ We have web site, documentation, tutorials, blog posts. It is not perfect, and could be improved but people use the library. Metrics: 10k stars at GitHub, 11k downloads per day https://pypistats.org/packages/albumentations https://pypistats.org/packages/albumentations We have 100s of bug reports / feature requests and someone needs to go through this. Even when someone picks a feature, writes code and creates pull request, core team member needs go through it, and typically there are a few iterations before the PR is merged. In our case we would like to hire full time engineer to do all this stuff. But it is money. => donations may help more than advice from the blog post, although I agree with every word in it.

euroderf 4y ago

When the subject is documentation, I wonder whether the "docs as code" approach can make documentation both more findable and more easily contributable-to. Put the (Markdown) docu for Foo in the same directory as Foo itself, making it super easy to keep the Foo docu up to date... while leaving it to a project meister to pull these somewhat scattered info-items (for the myriad values of Foo) into final user docu.

atoav 4y ago

As a programmer who studied philosophy and worked as a freelance graphic designer I often contribute in terms of writing, clarifying, creating explainer graphics, logos, splash screens etc. The issue with all of these fields is, that there is a ton of personal taste involved. As a professional I know how to push my taste aside and create something that serves a project — but not every contributor who will contribute e.g. graphics will be able to maintain that distance. This can potentially lead to emotionally exhaustive situations, where a maintainer or community is thankful for a contribution, but they have to say "no thanks" because the graphics/text don't fit the standard of the project. Same thing goes for well meant "analysis" where contributers ignored all existing issues and discussion — nice of you to do that, but consider that ot also creates work.