Getting set up to contribute to an open source project ranges from being technically fairly easy to requiring a long series of steps including many interconnected software installations and several interconnected codebases.
Repairing or improving documentation has a reputation as being an easy way to begin contributing to a project. Newcomers can often make improvements to the documentation for such things as how to get a thing to run/compile because they will be going through that process and might run into an issue or outdated part of documentation. They are then in a great position to improve it based on their experience.
When developers resist documenting, it is usually around several themes:
Developers often don’t like technical writing or think that writing is not a principal skill.
Developers want to get on with new engineering problems instead. In OSS, developers are volunteers and writing documentation takes up more of their free time.
For commercial projects, priorities may be on releasing new features and there may be little to no time to write documentation as it is not viewed by management as valuable.
The techniques for creating an OSS community that attracts contributions from project developers are mirrored answers to the above-mentioned problems.
Dumping down words in to a text editor is not very hard; many developers write copiously in email, for example. The documentor’s challenge is finding this content wherever it is (mailing lists, IRC discussions, random wiki pages) and editing it in to something comprehensive that reveals content holes for filling. The documentation project’s success hinges on the ability to restructure rambling content and make all of that accessible to new writing contributors, so they can begin meaningful work from the very start.
A metric of this success is when any random experienced contributor is asked a question by a new contributor, and in answering, insists that the answer be documented, for example, on the project wiki using existing templates, etc. In this way new contributors are turned in to documentors who share the work burden from the existing contributors.
Subsection6.2.2Getting Involved Through Documentation
Once you have identified an OSS project with an active and welcoming community, what steps should you take to become involved? Communication is the key to a healthy community, so here are some steps you can take to begin:
The first step is to learn to use the software. For web-based applications, this is often trivial. We all know how to use the Firefox browser, for example. For software that requires installation, you will likely follow directions on the website or in an INSTALL file from the repo. If needed, check out the examples and tutorials. Seeing an example of how the software works will help your understanding of the overall project.
Asynchronous Communication Channels.
Familiarize yourself with the communication channels employed by the community. If they have a Discord or Slack Channel, Google Group or other mailing list, sign up and read through other recent posts there. If this is a community, you want to stay engaged with, turn on notifications for some of the most relevant channels.
Starting with the README, CONTRIBUTING, and CODE_OF_CONDUCT, read the documentation that seems most relevant to your goals.
Following the Documentation.
Because opening issues about unclear, incorrect, or out-of-date documentation is an excellent place to begin contributing, if you want to start contributing, follow the documentation very slowly and deliberately, taking note of places where you experience confusion.
Synchronous Communication.
Some groups also have IRC and/or drop in video conferences that are open to all. Once you have a sense of the community, you can drop into these which will help you to become more integrated into the community.
Once you have something you want to contribute to the community, with the goal of setting up your development environment (see Chapter 3), slowly and deliberately follow the directions provided by the community to set up your development environment. Here again, take note of places where you experience confusion.
Open an Issue.
Once you have identified a place that documentation is confusing, wrong, etc, you are ready to open an issue. In opening an issue, most projects will have a standard format that you will want to be sure to follow.
Checkpoint6.2.1.Exercise: Getting involved.
Take a technical document content plan and prepare it to show to developers.
For example, create a personal user namespace on an open source project’s wiki “User:Username/New_page”.
Alternately, prepare it for inclusion in email.
Join the documentation mailing list; if there is no specific documentation list, join the main developer list.
Send an email with your content plan and any work done so far, request comments on content and where you are getting information from.
Proceed with writing a first draft of the content based on your plan and comments received.
If you get stuck, return to the mailing list or ask on their preferred communication channel. Your earlier introduction and content plan makes this part easier.
Return with your next draft to the mailing list, asking for a review and comments. Provide enough time, several days to a week, and be sure to engage in discussion about the content in a timely way (at least once per day.) The goal of this step is to improve the content’s accuracy.
Checkpoint6.2.2.
Why is improving documentation considered an excellent way for newcomers to contribute to an open source project?
It allows newcomers to showcase their technical skills in coding.
Improving documentation is not directly related to coding skills.
Developers often prefer newcomers to work on documentation instead of coding.
While developers may appreciate contributions to documentation, this is not the primary reason why improving documentation is considered a good starting point for newcomers.
Newcomers have experienced the process of setting up the project and can improve documentation based on their experience.
Correct! Newcomers can often make valuable contributions to documentation because they have gone through the process of setting up the project, which allows them to identify and improve parts of the documentation that might be unclear, outdated, or confusing based on their first-hand experience.
Improving documentation is viewed as less time-consuming compared to other contribution tasks.
The time consumption of improving documentation is not the primary reason why it is recommended for newcomers to start with documentation.
