Coding is creation unleashed. Your imagination runs wild and your mind conjures bits to do your bidding. You enter the zone and whip up some insane unrolled loops for your micro-optimization that produces a gigantic effect when run at web-scale™.
You are a god. You created. You made something appear where previously there was nothing.
And you made it public and open-source so that all of humanity can feel the positive, momentous impact of your contribution.
All the user needs to do is... wait. Yeah, sure, please, scroll up your bash history to find what the proper steps are. Nice. A big wall of text paste directly from your terminal into the Github markdown triple-backtick code block that will just monospace the hell out of it.
Because, surely, any noob can just read what you have executed and replicate those.
Right? RIGHT?!
ಠ_ಠ
Of course this is relative to your target audience. Sometimes it is quite sad choosing to limit your target audience to people running on the exact same hardware/software setup at the same time (i.e. no more than 6 months later). And that's effectively what quite a lot small hobby projects are doing.
Because if you are not running the exact same distribution and its version you will most probably run into compatibility issues with library versions, package names and other eldritch horrors that should've been buried a long time ago, but still lurk in corners.
That's where documentation comes in. Documentation about:
- what exactly are the requirements
- how to get those requirements.
- what versions are supported etc.
- how to build your system
- what are the command-line parameters it accepts
- does it depend on environmental factors (presence of directories / ENV vars etc)
And so forth.
"But you can always just run mycommand.sh -h"
Sure. If you can actually get it installed. (Sidenote: if your program does not support --help, (ノ ಠ益ಠ)ノ~ (\;｡▽｡)ヽ).
There's a reason why projects such as tldr exist. It's because a lot of documentation sucks. But of course there are more reasons for the suckiness besides just lack of time. People understand things in different ways, and I personally have met people who are able to consume the contents of manual pages without Examples section, but I personally am not one.
And now we finally get to my original point of this post.
Contributing to open-source isn't just about code
Disregarding all bad PR that writing documentation gets commonly among devs, it is still almost as important as the code itself.
Almost because no code + beautiful docs = a good plan, code + no docs = possibly shippable solution to an urgent problem. But that should be changed to code + some docs ASAP or otherwise you will have a ticking time-bomb on your hands.
But how can you get started with documenting if you don't even know how the system works, because it is lacking the docs that you wanted to contribute?
Well it is not as much of a catch-22 as it at first seems like.
There are two types of docs that you can contribute:
- From scratch documentation that actually requires you to read the source-code or at least interview/probe the author for the magic sauce.
- Fact-checking, spell-checking, typo-fixing, formatting
I'd say that the easiest way to becoming an open-source contributor is by doing the latter.
Is the documentation up-to-date? Does mycommand -l actually do what it is documented as doing? Have some switches been deprecated? Are there new features that are being used by the developer(s) but could potentially be of use to others if only they knew about them? (Posting about them in changelogs / commit messages does not count).
Is the documentation riddled with simple typos, grammar snafus or simply incomprehensible sentences and long-running paragraphs?
Every single typo a potential user finds while reading the docs will decrease the credibility of the product itself. Every. Single. One.
"If they didn't manage to write that simple word correctly, how could they have managed to write this complex piece of software without similar faults?"
That's a thought process that I have found myself going through on many an occasion.
Language matters because it is communication. Typos matter. Speak what you want of grammar nazis and other such derogatory terms, but such talents should/could be put to use in making the open-source a better place.
.oO( All hail grammar na.. nope, that doesn't feel right, nevermind...)
If you have any word processor that has a spelling database, run the documentation through it, exempt technical jargon or add it to your dictionary, and see if anything glaring pops up.
If you find your instead of you're, fix it.
If you find wierd insted of weird, fix it.
If you find a double negative where a correct positive term would be clearer, fix it.
If you find yourself reading the sentence over and over again, split it, fix it.
There is no such thing as a fix too small.
Hell, I would argue that the smaller the fixes, the less likely they are to cause any sort of issues with the project owners merging it to the main codebase.
Of course, you can have multiple typo fixes in a single commit and/or pull request, so you don't abuse the mental resources of the maintainers, but don't wait for perfection -- i.e. "all done" -- just commit and contribute.
Example A:
Dad gets his 4-year-old daughter to make a git commit to the Linux kernel
The diff was this:
1.9 Ext4 file system parameters
- ------------------------------
+ -------------------------------So they added a single dash. Yes. They added it and went to the trouble of committing (well their parent anyways).
That's quite a lot more code than most open-source users have ever committed to the Linux kernel -- or, mostly, to open-source in general.
Another example can be found in my own Github history:
As a former developer, it feels kind of weird to be contributing just small typo fixes, but the reason why I did is because as a reader of said docs I was feeling less confident in the software I was about to use. I wanted to make other learners feel more confident.
Github makes it ever the more easier as it has a very wizard-like experience for creating your fork of some code, changing the file online in your browser, committing, and finally creating a pull request for it.
Main picture CC-BY Ruiwen Chua - https://www.flickr.com/photos/ruiwen/3260095534/