How To Contribute To Open Source Documentation

Since the early 1990’s, the open source community has enjoyed a high level of success. With projects like Linux and Apache Mobile, people have been able to enjoy top quality software for free!  This is all made possible by a robust and passionate community of developers and designers who contribute their ideas and energy. It is this community—and its generous sharing of knowledge—that has powered the open source world for so long. The Free Software Foundation encourage you to contribute your expertise through documentation.

Open source projects are always in need of new contributors to be able to do the great work they do. There are many entry-level positions that you can still help with even if you don’t have a lot of time or expertise. This article will cover the different ways you can make contributions and things to keep in mind if you’re just getting started.

Look for and read the CONTRIBUTING.md file

Normally open source projects have a CONTRIBUTING.md file in the root of the file system. In gulp it looks like this:

File List

Open it up and you’ll see how to contribute.

  • ideas: participate in an Issues thread or start your own to have your voice heard.
  • resources: submit a PR to add to docs README.md with links to related content
  • outline sections: help us ensure that this repository is comprehensive. if there is a topic that is overlooked, please add it, even if it is just a stub in the form of a header and single sentence. Initially, most things fall into this category.
  • write: contribute your expertise in an area by helping us expand the included content
  • copy editing: fix typos, clarify language, and generally improve the quality of the content
  • formatting: help keep content easy to read with consistent formatting
  • code: Fix issues or contribute new features to this or any related projects

Out of the seven ways to contribute, code is the last one. So there’s plenty of ways to help out.

Understanding how a project works

Not all open source projects operate in the same way. Some allow contributions from anyone. Some require you to work your way up to get contribution privileges. Some have multiple people involved in managing a project. Others have a single person in charge, a so-called benevolent dictator for life. 

Contribution guidelines help you understand how to approach your participation in a project. It will explain how to reach out about a contribution, provide templates for communicating bugs and suggesting features, list work that is needed by maintainers, project goals, etc. An amazing example is the Angular contribution guide which lists all kinds of useful information for new contributors like their commit message guidelines, coding rules, submission guidelines, etc. in great detail. 

In addition to contribution guidelines, some projects will have a code of conduct. It usually outlines community rules and behavior expectations. It’s meant to help you know how to be a amiable and professional contributor and community member. Angular, for instance, has an awesome code of conduct that lists what they consider unprofessional conduct, their responsibilities to the community, and how to get in contact in case someone violates it.   

Big projects may have governance policy and team documents that outline specific roles in the community, teams, sub-committees, contribution workflows, how discussions are conducted, and who gets to commit. These kinds of documents are essential to understanding how the community operates. The about page on angular.io, for example, lists who all the core team members are, their roles, and other contributors. On Github, they also have a docs folder containing policies regarding contribution.  

Even after you’ve gone through the documentation, you may still need to ask questions to active members of the community. Despite doing your research, you may still be stumped on a particular aspect of the project. To interact with other contributors, join community communication tools like Slack, IRC etc., sign up for newsletters, and subscribe to their mailing list. Angular uses Gitter as its community communication tool and directs contributors with questions/problems to Stack Overflow, where they can get help using the angular tag. Connect with community members and develop relationships with them as it will expose you to facets of the project that you may be unaware of. 

Having a good grasp of the technical aspects of the project and how it’s organized is essential to making contributions that meet the project’s standards. To understand technical parts of the project, consult the project README, wikis, tutorials, and documentation. Angular, for example, has docs explaining their Github process, building and testing, their coding standards, debugging, PR reviews, etc. Going a step further, look at past feature integrations and bug fixes in merged pull requests which are full of discussions by other contributors and can be a rich source of context. As the project evolves, pay attention to it, frequently follow issues, features, discussions, pull requests, and bug fixes to continually learn how it works. For instance, a contributor can follow this example of an Angular feature request discussion about a form API to better understand how Angular forms work, bundle size management, etc.

An open source project is sort of like a project at any company you might work at; there will be a house coding style, team culture, and workflows for getting things done. The difference is that open source projects can and will have a much different group of people working on them.

Have a consistent contribution process for code and documentation

 We also recommend having a consistent contribution process and using the same toolchains for code and documentation. As we noted earlier, many new community members start contributing by working on documentation, as you often don’t need deep technical knowledge of the software to get started. It’s good for new contributors to onboard in the community by getting familiar with the contribution workflow and meeting other community members. If these new contributors later want to get involved in other parts of the project (including code), you want the toolchains and contribution process to be familiar. Otherwise, they will need to go through another onboarding process, which creates an unnecessary hurdle for contributors. If your code and documentation have different contribution processes, you may risk creating an impression that documentation is less than a first-class citizen compared to code.

Fork the Repository

Once you’ve figured out what you want to contribute hit the fork button at the top right.

Fork Button

You may be asked where you’d like to fork it if you’re part of an organization.

I’m going to select my own github account.

Prompt to where to fork - my personal account selected

If you don’t see this you’ll have already forked it onto your own account.

Notice how in the top left there’s your username followed by the repo name and below, where the originating repo is.

An image showing the forked repo

This means you have it forked correctly.

Finding projects to work on

One way to find projects to work on is to look to open source software you use often and like. Is there a tool, package, framework, or a language that you work with regularly and enjoy using? Find out whether it’s an open source project by checking its license and if it accepts contributions and is active. Working on things you already use gives you an edge when contributing because you’re already pretty familiar with how it works and have experience using it. As a bonus, you can address problems that have been bothering you or suggest features that you want in the software. If you are going to contribute code to the project, be sure you can work in the language it’s written in. 

If the above approach may not work for you, try using the Github explore page to find projects that are accepting contributions or actively want help. Github suggests projects you may like based on people and repositories you follow, star, and watch. Another way to find projects is to use Github’s search tool by entering beginner-friendly contribution tags like good-first-issuegood-first-bugbeginner-friendlyeasylow-hanging-fruitfirst-timers-only, etc. Filter search results to return issues in open states and in the languages you’d like to work in. There are tons of other tools, platforms, and programs where you could find open source projects that I’ll list at the end of this article to help you with your search. 

To have a positive contribution experience, try to avoid communities that are hostile to beginners and generally problematic. If for example, when trying to ask legitimate questions after you’ve done your research, you receive dismissive and combative comments or insults, it’s best to stay away. Another sign to be watchful for is a pattern of unprofessional behavior within a community. Some open source software projects have been infamous for this sort of thing. So do your research before contributing.

Value contributions to documentation just as much as code contributions

 A lot of the focus in many open source communities tends to be on code. One easy way to make sure documentation contributions are valued by everyone is to give equal credit to documentation and code in your community metrics. It should not matter whether a commit, merge request, or pull request is for code or documentation. In addition, when you do community recognition, include key accomplishments by the people who contribute to documentation.

Conclusion

The great thing about open source software is that it’s freely available to everyone, and if you find a bug or want to propose a new feature you can contribute. This is an overview of how to contribute code to an opensource project.

0 Comments

No Comment.