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.
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.
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.
> 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.
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.
That's a very good habit to be in, however when it comes to external-facing stuff, e.g. APIs, or stuff that needs a lot more detail (and especially examples) then you're going to need more than self-documenting code.
Of course getting out of sync is a real massive issue and a total pain. But that's another reason for people to contribute to such things :)
For APIs, there are tools to parse out comments (that the linter requires) into the API description. Doesn't give examples or much of a "when to use this" usually, but I've found it's better than nothing.
For me personally, even though I dislike these auto-generated docs since they're quite terse (and tend to display niche parts of the API just as prominently as the parts you likely want to use), I tend to find them much more reliable than more detailed guides precisely because they tend not to desync, so I often don't even bother with well-written guides anymore, since they are much more likely to waste my time (or at least be inaccurate).
I'd expect many other developers have the same level of trust issues I do, to the point that those shitty auto-generated docs are in some ways better than really nice, detailed docs, because they are easier to trust. I'm unlikely to break the habit of ignoring detailed docs/guides unless it's coming from some big project where they're uniformly good. Otherwise, reading them tends to be a waste of time IMO.
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.
I understand the sentiment, but for me, I actually prefer writing the documentation myself on my projects. It forces me to make sure that I understand the PR that's coming in, since I'm going to have to maintain it into the future anyway. I also want to maintain a consistent organization and style in my documentation that is difficult to explain to other people. So it's far easier to write it myself, than to ask the contributor to go through review cycles on the documentation.
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.
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.
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.
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.
> 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.
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.
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.