As part of Sonatype's partnership with the Cloud Native Computing Foundation (CNCF) for our Security Slam event aimed at helping improve security of open source projects, we created a series of blog posts on best practices for open source maintainers.
Here in the first post of the series, we focus on the basics of good documentation to attract new contributors and lower the barriers to contribution.
So, how do you instantly show the ease-of-use and immediate applicability of what you built?
Better documentation.
You can find similar sentiments in articles like this one from the New York Times, where they posit that "one of the biggest pitfalls for open source projects is a lack of documentation."
Your project probably makes sense to you. It's a solution to a problem that needs to be solved. So you parsed out the pieces and assembled a tool that's freely accessible and empirically useful. But prospective users did not witness your linear progression of problem solving. They heard about it, read about it, or stumbled upon it, and now they're at your repository and need to deduce its value without any roadblocks in a matter of seconds.
Thankfully, popular formats of documentation exist to serve exactly this purpose for your project. While the capabilities and use cases of open source projects differ widely, the majority of projects contain one or more of the following pieces of content in their repositories.
README
A project's README file tells prospective contributors and users what your project is all about.
Oftentimes the README is the first interaction a user has with your project. Your fellow developers want to solve problems, so a README that contains clear, concise, and necessary information that shows how to get started gives you the best chance of a great first impression.
Start with a plain text file (Markdown is the most common). Next, the README should be straightforward in covering the fundamentals.
Here's our recommendation for items every README file should contain:
- an overview of the purpose and goals of the project
- installation and basic user instructions
- methods of communication for the project
- links to contribution guidelines
Most developers enjoy writing code rather than documentation. So, it's not uncommon to feel that writing a README file is a struggle. If you find yourself in this situation, just focus on answers to these fundamental questions:
- Who is the specific audience for this README?
- What information would help encourage contribution to my project?
- Why should my audience read this?
- How could this README help that audience?
The goal here is to create a well-put-together README file that provides a warm welcome to new community members. Be sure to not go overboard, and only include the necessary information to get started. And if you need even more help, check out this article at FreeCodeCamp.org — it lays out in even more detail how to write the perfect README.
CONTRIBUTING
While your README covers your project's fundamentals, another file ensures your contributors understand ground rules on how to interact with and contribute to your project.
Typically, this information resides in a CONTRIBUTING file (often in Markdown). With this document stored right in your GitHub repository, you display canonical information that will help a contributor when they wish to open a useful issue or submit a proper pull request.
A CONTRIBUTING file also can provide contributors with information on how they can get involved which encourages creation of user-generated content as you build your community.
For a simple template, look here.
CODE_OF_CONDUCT
A code of conduct defines standards of communication and participation with your project. With a CODE_OF_CONDUCT file (often in Markdown), you establish expectations of behavior by contributors interacting with your project and outline actions you can take to address problems among members of your community.
A code of conduct usually contains descriptions of the following topics:
- Scope of the code
- Community standards
- Methods for reporting issues and incidents
- Code enforcement
- Acknowledgements and/or links to previous versions
Consider what you are willing and able to enforce in terms of ground rules, and write your code of conduct accordingly. By establishing your community guidelines and enforcement of the rules, you simultaneously carry out your responsibilities as a maintainer and reinforce the behavior of a welcoming environment.
Here are a few good examples of how to lay out a code of conduct:
Sometimes a project's official code-of-conduct information simply resides in a README, sometimes it's in its own Markdown file in the repository, and other times it's nested within the CONTRIBUTING file. It's your discretion to determine which method works best for your project. For a simple open source template, look here.
SECURITY
What's the best kind of application security risk to fix? One you discover before it's found by bad actors. Responsible disclosure is considered the most ethical way of disclosing vulnerabilities and involves giving the vulnerable project a heads-up before public disclosure.
Make it easy for ethical hackers to report vulnerabilities by creating a SECURITY file (often in Markdown). This file defines your project's security policy and gives instructions on how to report a vulnerability privately.
Better documentation helps build better communities
Clear guidance communicated via documentation reduces complexity, conveys technical capabilities, and (most importantly) helps contributors and users get started. To encourage others to invest time in contributing to your project, you need to quickly and concisely convey that it’s possible to navigate your codebase with confidence.
Foundational documents such as README, CONTRIBUTING, and SECURITY files encapsulate information effectively and efficiently in industry-recognized formats and fulfill the first step to building a community.
