Documentation as a gateway to Open Source
Documentation is a vital part of any open source project or software.
It is the entry point or a fall back option for users of any open source project or software to read usage, installation instructions, to fix issues and learn more about the project.
So a poor documentation will lead to nothing else but limitation of the reach on that open source project or software.
Me as a person, I don't stay long on poor documentation page of any project, I will rather find an easy and detailed alternative to such a project.
A nice example of projects that are still finding it hard to keep up with their documentation updates are JQuery, SQLite.... and a nice quote from Write The Docs says it all.
“If people don’t know why your project exists,
they won’t use it.
If people can’t figure out how to install your code,
they won’t use it.
If people can’t figure out how to use your code,
they won’t use it.”
— Write The Docs
Lets jump in;
1. FInd a project: Projects that you understand
Most of my contributions to open source projects was through the usage of those projects and familiarity of those projects.
So when looking for open source projects, It's better to look into software that you have used or planning to use later.
The next thing you should do is hit google or github to look for the project, to see how active their repositories are and how they handle contributors.
If it's cool to you, then you can proceed to see what you want to improve in their documentation .
Better still to see how you can make life easier for the next person.
A very good scenario of this that i can share is when I got successful with the deployment of Docusaurus with Firebase.
So you see, I used the project and I was able to find something to contribute to.
Also, you can reach out to existing open sourcerer (People who are already contributing to Open Source) to ask them which projects are good for new contributors,
You can find some active documentation of open source projects by alot of organizations here also Awesome OSS Docs which takes and accepts beginners contributions.
You can find other excellent resources and Jobs/Documentation/Writing gigs at the Write the Docs community.
Another great way of looking for projects is through the use of GitHub’s Topic page.
Go to “Explore” and then “Topic”.
Here you can explore a lot of topic based projects.
There is also a "Documentation" Topic which contains a lot of documentation projects.
Once you’ve found a project, you’ll want to keep in mind some basic contribution etiquette as you get started, let's move to that.
2. Digest the Project guidelines and rules
Now that you have found a great project to contribute to, before getting ready to contribute, you need to do a little work, understanding the Open-Source project contribution guide.
It's always named ‘CONTRIBUTING.md’. Read this file carefully to learn how to contribute to the project.
It typically includes guidelines on what to branch, test, how to format your commit messages and clear step-by-step instructions on how to make a contribution.
Most projects have some prerequisites that you need to follow to set up the project properly.
Ask the maintainers where they need help around their documentation.
If you found an issue that you want to tackle, comment about it, and let everyone know that you wish to work on that issue.
Explain what problem you wish to solve or which new feature you wish to introduce.
Give the maintainers time to respond to it before beginning your work, remember that many maintainers have day jobs or limited time and may not respond immediately.
Also many repositories will have an issue template prefilled when you create a new issue. Stick to this template!
When you are done digesting the guides, it's time to then look for where on the projects to contribute too.
-
READMEs
Not all open source projects do have a documentation repo or a dedicated documentation folder,.
Some projects always leave their documentation in the README.md file and it is always located at the root of the repository.
The readme file does contain installation guides, how to use guides and in some projects it can be much more than that.
So you can try out the installation guide to see what works and what doesnt work, an example is a Subdomain Recon tool.
See their old installation guide, which doesn't work well for others and the update of the new installation guide that works.
Old ReadME
New ReadME
You see making a correcting Improvement to the installation guide and instructions will help any new user of the tool.
You can also move on to fixing any Grammar, Spelling and formatting issues you find in the README file.
-
API Documentation
People tend to leave out API Documentation when they are talking about documentations.
You can always contribute to the API documentation of any project you find interesting and if they have an API implementation, you can help improve the documentation.
API Documentation is simply a technical design document that guides developers on how to consume, use and interact with an API.
The API Documentation is made up of code snippets, references, methods, tutorials and formatting rules.
You can also work hand in hand with the backend developer or maintainer of the project to get guidance on what some API endpoint does and so on.
Various contribution opportunities like versioning of the API, So if the project maintainers are already working on the V2, V3(version 3)... of their API.
You can always reach out to them, to see how you can help them with the documentation, you can also check this guide to learn more about API Documentation
-
Commands, Error Message, Code Strings, Language Translation
Here is another nice way of contributing to open source projects, Error Messages, Code strings and commands.
Most documentation are formatted in English, and we both know, people with other languages might make use of your project.
If they dont understand English, they might find it hard to use the Open Source project, so its' always nice to have documentations in different languages.
That creates an opportunity for an individual that understands multiple languages to contribute and help translate the documentation into other languages.
So if you understand other popular language like chinese etc., you can always reach out to the project maintainer to request for a go ahead to help translate the documentation.
Error messages, Code strings are also important part of any project, Yeah the nice interface messages, this is what users see, this message is what guides users, and gives them direction on how to debug issues, navigate in your project.
If you have a very poor Error message or Code strings messages, this will give a bad experience to the users of the project.
So here is an opportunity for you to pick the errors, typos messages and fix, this is also very nice way of contributing.
Yeah, thats all, so to the no code people, this are the ways you can start contributing to open source projects easily, you can also further your learning about other types of documentation that are available
This will provide you with a large scope of different ways of contributing to open source project via Documentation.
Well, we are done with that, but wait, what if you were given the opportunity to pull up a documentation page for any open source project that doesn't have one yet?
That brings us to the Documentation Toolkit for those awesome documentation lovers, here are the list of things you will need to get the task done;
Documentation Toolkits
- Documentation Site/Page Generator:
- Docusaurus — (Here is a guide on how to spin up a documentation page easily with docusaurus)
- StoryBook
- Technical Skills: Git and GitHub, Markdown
- Grammarly(Grammar spelling checker)