Non-Code Contributions to Open Source (2021) | Hacker News Reader

Non-Code Contributions to Open Source (2021)

navendu.me

67 pointsasicsp24 comments

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.

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.

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"

If you can't describe teh problem sufficiently then the bug can't be fixed, or you're loading the problem onto the dev.

> No, I am not going to spend 10 minutes filling out this report,

Then it won't get fixed

> but I would be happy to send a brief message describing my issue.

Which often ain't going to be enough. You're now wasting everybody's time

> You're probably just going to close it in 3 weeks automatically anyway.

Jesus that's so cynical smug. My request: don't use any open source software. Pay for it. Leave open source developers with people who can be bothered, if you can't be bothered to give anything back at all.

I feel like "managing bug reports" is something missing from the list OP posted.

Getting information and logs from users, checking if a new bug is a duplicate, attempting to reproduce bugs, and triaging, are all things that can take a long time, but don't necessarily need to be done by a developer.

> don't necessarily need to be done by a developer

Yes and no. They need to be done by someone with developer empathy, for example a hyper-enthusiastic user champion, and hands-on problem solving experience definitely helps a lot.

Reproducing bugs and triaging issue reports does not require the skill of reading and writing code, it does require the skill of systems thinking which is IMHO a developer trait.

Yep. See the Home Assistant devs. They implemented a bad “hack” that forced some DNS settings and when it was reported and they were called on it they doubled down instead of fixing.

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.

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.

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.

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.

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.

> 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.

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.

It is the same for me. A tutorial to get me started and then docs once I'm comfortable using it.

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

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.

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.

I would add to the list - donations.

I am core developer of 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

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.

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.

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/

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

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.

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.

Reply on news.ycombinator.com