Skip to content

Chapter 11: Building a community

Your README needs to make a value proposition

  • The README file is your elevator pitch.
  • Use visual aid whenever its relevant (e.g.rich project)

Provide supporting documentation for different type of users

  • The funnel of users: Potential Users -> Users -> Super Users -> Contributors -> Maintainers
Hint

The README and documentation How-To files quality are the most important text artifact in your project to gather Potential Users and Users. The code quality of your code makes the transition between Users and Super Users. Finally, API, reference documentation and a historical of the project reporting the vision and architectural decisions will encourage some Super Users to become Contributors. Experience and trust will lead to the final transition in the funnel where Contributors become Maintainers.

  • To attract users, your project should offer easy-to-follow setup instructions.
  • Adding a CONTRIBUTING guideline will standardize contribution procedure which in turns makes the process more efficient. It also helps to reduce friction between new contributors and maintainers.
Hint

You can add your CONTRIBUTING file in your .github project folder such that GitHub will automatically show up this document whenever a user opens an issue. It is also a good idea to link this file in your README.

  • Architectural Decisions is a valuable piece of documentation that will help new contributors to understand the vision and direction of the project but also help you to understand why things are the way they are, which may not be evident after a longstanding project.

Establish, provide and enforce a code of conduct

  • A code of conduct will maintain a safe and friendly space among contributors.
  • The main goal of the CoC is to keep a toxic/troll-free environment.
  • Check the Contributor Convenant for a start template.
Hint

The same hint for the CONTRIBUTING file is valid for the CODE OF CONDUCT file. Consider to add it in .github folder and link it in your README.

Track high-level changes in a CHANGELOG

  • The CHANGELOG file helps users to easily identify the changes between two releases.
  • You can use keepachangelog to format your document.

Issue templates

  • Standardize the way issues are reported.
  • It helps everyone to understand the scope of the issue and how to reproduce it.
  • Github offers some template ideas.