Documenting for Open Source¶
Description
In 2017, I opened up a project of mine—a JavaScript-based countdown clock to Halloween—to the open source community as part of Hacktoberfest. Within a few days, my project had generated a surprising amount of traction. Enough traction, that I had difficulty managing the request for changes in a timely fashion. Realizing that I was one person, maintaining a codebase in my spare time, I knew I needed to find a way to streamline the project so that I was working smarter, instead of harder.
Enter documentation!
While researching best practices and guides on maintaining an open source project, I learned that the #1 problem encountered in open source is incomplete or outdated documentation. This was huge! Knowing this, I could use documentation as a way to:
- Be upfront about Code of Conduct expectations, licensing, goals, etc
- Provide an overview of the project, including technologies used, how to contribute and frequently asked questions
- Create fill-in-the-blank templates for common for pull request & issues to ensure all necessary information is provided upfront
- Provide a log of changes made, bugs features added over the life of the project
While I am far from a documentation expert I believe that open source projects—and their supporting documentation—can and should be inviting to people of all skill levels. Documenting items like how to get started, where to find key files, expectations, etc are easy wins that positively impact how people interact or contribute to your project.
Source: https://opensourcesurvey.org/2017/
- Conference: Write the Docs PORTLAND
- Year: 2019
