[HN Gopher] Non-Code Contributions to Open Source (2021)
___________________________________________________________________
Non-Code Contributions to Open Source (2021)
Author : asicsp
Score : 59 points
Date : 2022-09-26 10:32 UTC (12 hours ago)
(HTM) web link (navendu.me)
(TXT) w3m dump (navendu.me)
| stared wrote:
| 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 wrote:
| 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.
| bawolff wrote:
| > 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 wrote:
| 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 wrote:
| It is the same for me. A tutorial to get me started and then
| docs once I'm comfortable using it.
| prego_xo wrote:
| 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.
| gorilla0 wrote:
| 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.
| antirez wrote:
| 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.
| ctrlmeta wrote:
| 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.
| euroderf wrote:
| 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.
| marcodiego wrote:
| Simply being a user is a form of helping FLOSS. It helps to
| weaken the argument "nobody uses that".
| jjzhiyuan wrote:
| "Helping Newcomers" onboarding is also a very important
| contribution to open source community!
| MayeulC wrote:
| 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.
| ternaus wrote:
| 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.
| Timwi wrote:
| 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.
| RobotToaster wrote:
| 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.
| calvinmorrison wrote:
| 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 wrote:
| 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"
| zasdffaa wrote:
| 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.
| xcrunner529 wrote:
| 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.
| pkz wrote:
| 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.
| setgree wrote:
| 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/
___________________________________________________________________
(page generated 2022-09-26 23:02 UTC)