Contributing Without Code

https://popey.com/blog/2020/12/contributing-without-code/

by pabs3 • 6 years ago

115 26 6 years ago

Great write-up. Another way to contribute is with articles / write-ups to help others or to highlight / uncover hidden gems. See the 25 Days of Ruby Gems - Ruby Advent Calendar 2020, December 1st - December 25th [1] page or the upcoming Ruby Blockchain Week 2021, January 3rd to January 9th - 7 Days of Ruby (Crypto) Gems [1]. Contributors without code welcome.

[1] https://planetruby.github.io/gems/

zerop• 6 years ago

I really appreciate your self-recognition. Your contribution is as invaluable as anyone part of Ubuntu and I am glad you shared it. Somehow I find more people looking for outcome driven goals rather than these kind of efforts.

pabs34• 6 years ago

Thanks to dang for adding this to the second-chance pool :D

kowlo• 6 years ago

What does that mean?

jwilk• 6 years ago

https://news.ycombinator.com/item?id=11662380

Moderators and a small number of reviewer users comb the depths of /newest looking for stories that got overlooked but which the community might find interesting. Those go into a second-chance pool from which stories are randomly selected and lobbed onto the bottom part of the front page.

pabs34• 6 years ago

I note that Debian has lots of non-technical (and less technical) ways to contribute:

https://www.debian.org/intro/help

barnacled2• 6 years ago

I contribute to the linux kernel and one key part of it is its extensive documentation - one of the patches I made was to correct some invalid offsets there - there is so much that can be done there that isn't code.

If even the kernel which is pretty specific low-level stuff can benefit from that then more-so pretty much any other open source project, and extremely value for it! Good technical descriptions are surprisingly hard to find.

yodsanklai• 6 years ago

Good technical descriptions are surprisingly hard to find

Totally agree. It seems many developers don't like writing documentation. Good documentation can save hours of work to tons of people. It's a great way to make a positive impact to a project.

I'd like to have counter points of view, but I feel that lack of documentation led to the demise of many open source projects.

smichel17• 6 years ago

The argument against is just about effort. Maintaining documentation takes a stupendous amount of effort. Largely due to the language it's written in: dynamically linked and typed, tons of overloading, no formal specification, and 7 billion different interpreters.

Writing documentation is relatively easy. Writing clear documentation is hard. Writing clear documentation and ensuring it stays up to date is, if not an order of magnitude, at left several times harder than doing the same thing in code. To the point where it's less effort to re-answer the same questions over and over in an issue tracker (and others can help keep track of your responses) than to maintain up to date docs.

My preferred approach, on smaller projects with limited numbers of people, is to push documentation as close to the code as possible. Prefer comments, tests, and types over standalone docs, in that order. Prefer not to duplicate the code (explain why, not what, is being done; consider using intermediate variables with descriptive names rather than a comment on "what"), unless it is a public interface and you want to restrict the intended behavior to some subset of the actual behavior. Your standalone docs are now about the high level stuff, filling in the gaps between file-level comments and directing the reader to the right files/code to look at. Generated documentation from the types and comments helps make this approach more readable.

Here's an example: a project I'm working on now had several shell scripts to automate common tasks (e.g. setup). Each script starts with:

    #!/bin/sh

    usage()
    {
    cat >&2 <<'USAGE'
    Description here
    USAGE
    }

    set -eu
    trap 'test $? -eq 0 || usage' EXIT

In other words, an explanation of how the script is intended to be used is embedded at the top of the file, and printed any time there is an error (e.g. invalid arguments). And the readme clearly states that if you want to understand the scripts, you should go read them. This is so much easier to maintain than a comment in a standalone doc, that you KNOW I'm going to forget to update when making tweaks to the script. And although I'm not doing it now, it is machine parse-able if I wanted to generate docs from it.

otterley• 6 years ago

Good documentation is so important that I do not merge pull requests to my open-source projects unless they're accompanied by documentation (with the exception of minor cosmetic changes). If you can take the time to code up something, you can take the time to document what you changed -- and why.

It's a travesty that this is not the norm for major open-source projects.

bregma• 6 years ago

The software community has always been a community first.

Effective communities are not always just cloistered monks singing a plainsong chant. They are more likely a diverse set of individuals with diverse talents and interests creating synergy. More of a full choir singing harmonies, with a backing orchestra and janitorial and front-of-house staff if I can belabour the analogy.

Anyone who uses software can celebrate being part of the community. There no reason to limit it to those who contribute code.

xMLAK• 6 years ago

Nice to see a true idealist from the 1990s/2000s who has really helped.

These days the first step for a non-code "contributor" is to draft bylaws and CoCs, get some fake "president" title in the project and proceed to suppress and feel superior to high performers.

Unfortunately, often the high performers aren't aware of their worth (there is a pg article that touches the subject) and give the power to those who do not deserve it.

yrimaxi• 6 years ago

HN hackers are known to be particularly modest.

rurban• 6 years ago

Which community are you referring to? In mine it was the very same, and I guess it's very common.

loloquwowndueo• 6 years ago

Thanks for your help over the years !

bernardv• 6 years ago

UofG in the mid 90’s.. I remember those days, when Gopher ruled.

z3t4• 6 years ago

People like this can make or break a community. Most of them just enjoy helping people. But then there are also a few who is in it for the power, as a community is like a small kingdom, their goal is to work their way up to get admin powers. Luckily you can only downvote once on HN. Imagine if you could shadowban people after 20k karma on HN.

MayeulC• 6 years ago

This oddly resonates with this article I read yesterday:

https://pointieststick.com/2020/12/29/how-kde-can-transcend-...

Nate has a look at the cycle of "early adopters, late adopters, and people who come for money and power" in every niche.

nerdponx2• 6 years ago

I have been specifically looking for ways that my UX and graphical designer friends can get involved in Free Software, both because they always seem to want more portfolio projects and because Free programs tend to have questionable UX.

It's not easy. A user interface is not an easy thing to change, so unless a developer consults a designer from day 1 (or has their own design chops), the application could be stuck with a suboptimal user experience for a long time, ultimately limiting adoption to geeks, hackers, etc.

pabs34• 6 years ago

The Open Source Design website lists paid and unpaid opportunities for designers to get involved in FLOSS projects:

https://opensourcedesign.net/

nerdponx2• 6 years ago

Thanks! I will share this.

milanove• 6 years ago

One thing I've noticed when using many open-source softwares with a GUI is that they just don't look and feel like a professional piece of software. The programming and project architecture may be stellar, but without a clean, professional looking user interface, most folks won't give it a chance. Take Gimp for instance. The software is an excellent alternative to Photoshop, but most people who aren't really into OSS or programming tend to overlook it or immediately disregard it, due to its UI.

Like the article's author talked about contributing answers to forum questions, I think other areas open-source software projects need some changes. I think the OSS community needs to try and recruit more design folks into their teams, rather than just programmers.

pabs34• 6 years ago

The Open Source Design website lists paid and unpaid opportunities for designers to get involved in FLOSS projects:

https://opensourcedesign.net/

Contributing Without Code

Related Stories