This article lives in:
(too long, didn’t read)
Newbies are great at docs, better than maintainers. Start with that.
Find a problem
First, find a problem that you want to solve, something that you care about.
If you see you can solve it easily without technology, cool, go and do that. And come back with a new problem ;)
Then find how technology could help to solve it, what kind of app or system would help.
Find a project
Then find an open source project that would help to solve that problem.
If there’s a tool that solves the whole problem, that’s great. But it’s more probable that you will have to divide the problem into smaller parts, and then find an open source tool that would help with some part of the problem.
Study that open source tool.
Read its documentation, try the examples, learn how to use it.
If it’s solving a problem you care about (or part of it) it will be useful, it will be interesting to study. And having a real-world objective for that tool helps you put the focus where it should be.
While you study that tool, there are high chances that the documentation has obsolete parts, needs updates, clarifications, etc.
Or simply, it could have been explained better.
Now, that you are just starting and have a fresh point of view with that tool, it’s the perfect moment to improve documentation.
You need some steps first:
- Learn how to make a pull request with change suggestions.
- Learn about the docs for that project. How they are created. It’s normally some text files in a directory in the same project, or in a sibling project. But you normally can just edit the small part that you found without having to learn everything about that project’s docs system.
- Fork that project to get your own version to change and propose changes to the original.
Update the docs
Now add documentation for that project.
Add the examples that would have helped you get started, with a focus on a simple real-life problem (like yours) that this tool would help solve.
Add the text that would have explained to you the same concepts more easily.
Add the definitions of the words the maintainer assumed were obvious but were required to know to be able to do the first steps.
Add documentation for the things that aren’t documented yet.
Update the things that seem complex or difficult. Once you understand them, think how someone could have explained them better to you, and write that.
Fix typos. There are always typos.
Any of those changes would probably be an independent pull request. Keep them separated, with the minimum changes, with a very clear scope. That helps maintainers accept just the things they are fine with.
After that, you will already have a bunch of contributions to open source. From there on it’s a lot easier.
But that’s a good way to get started.
The newbie advantage
If you are a “newbie” with that open source tool, if you are just getting started with it, you have a great advantage over the maintainers or any other more experienced developer that uses that tool. And it’s exactly that. That you are a newbie… you know nothing about that tool.
That means that you have a completely fresh point of view. You don’t take anything for granted with that tool. You don’t assume as obvious some basic concepts of the tool because you weren’t the same person developing it for months, knowing all its internal workings.
Also, you are actually reading the docs. And you are reading them in order. So, you can more easily spot things that could have been explained before or better. You can find inconsistencies in different parts.
And you won’t be reading it “like you know it”, it won’t be the 30th time you read those same docs, it will be the first. So, you will more easily be able to detect incorrect things, typos, etc.
A maintainer, an experienced user, or a contributor won’t normally spend much time reading the docs again and again, so, those “small” errors accumulate.
And a maintainer or the project creator will never have a fresh point of view, without all the background of having built the whole tool.
A newbie has a fresh point of view. And that’s an advantage.
Start with docs!
You can follow me, contact me, ask questions, see what I do, or use my open source code: