Reaching RMM Level 1 in My Repositories

After proposing the Repository Maturity Model (RMM), I wanted to put it in practice in my portfolio. The first step is to implement Level 1, which consists on writing the content to inform visitors about the repository and guide contributors through the process of fixing bugs and enhancing features. It doesn’t necessarily need to have working code, but anyone should be able to understand what the repository is about and how to contribute to it. I’m reporting here what we have done to accomplish that in all repositories.

Documentation is often neglected at the initial stages of a project. It might be due to the fact that “documenting” is less fun than “coding”. I agree with that, but in my experience, leaving the whole documentation to be written at the end is more painful than gradually writing it as the project evolves. Writing also leads to thinking and thinking is what we need to create great products. Amazon, Google, Twitter, Spotify and others have built a culture of documentation, and those who follow lean practices like to test ideas before implementing them.

Documenting since the beginning makes the content lighter, cleaner, better. It passes through several revisions each time someone contributes with more content. So a repository reaches Level 1 when it contains enough content not only for users and contributors, but also to give them a chance to document as they use and build the product. After getting some inspiration from opensource.guide, we came up with the following artifacts for Level 1:

• short description
• user guide website
• readme file
• code of conduct
• contribution guidelines
• license
• tags
• issue templates
• pull request template

Github somehow helps us to implement Level 1. When creating a repository, it suggests creating a readme file. It is then generated in the root of the repository. Github also has a checklist to make the repository welcoming to contributors, as we can see in the figure below.

You can find this checklist at “Insights > Community”. It automatically checks for the presence of files in predefined locations, completing the checklist as the following files are created:

• .github/ISSUE_TEMPLATE/bug_report.md (issue templates)
• .gitbub/ISSUE_TEMPLATE/feature_request.md (issue templates)
• .github/PULL_REQUEST_TEMPLATE/pull_request_template.md (pull request template)
• CODE_OF_CONDUCT.md (code of conduct)
• CONTRIBUTING.md (contribution guidelines)
• LICENSE (license)
• README.md (readme file)

We are left with short description, user guide website, and tags. The short description is the product summarized in a sentence, in the About section of the repository. It also includes a paragraph at the beginning of the README file, as highlighted in read in the figure below.

The figure also highlights the tags, which are commonly used keywords across Github. They help to make the project discoverable by Github’s search engine. We can also see the link to the user guide website above the tags. For the website, Github helps with Github Pages, whose configuration you can find at “Settings > Pages”. Any HTML content in the folder /docs is served as a static website. All we have to do is to generate that HTML content and publish there. We’re using Asciidoctor for that, which processes the Asciidoc format and generates a good looking HTML page, like the one below.

In the last 5 days, we went through all repositories, produced all the documentation required by RMM Level 1 and now we have all of them ready to receive code. The following table compiles everything that was produced.

Artifacts	digger	minimily	controlato	CSVSource	pycific	spitfhir	liftbox
Short description
Documentation website
README file
License
Code of conduct
Contribution guidelines
Issues templates
Pull request template
Tags

There is a reasoning behind the open source licensing of these repositories. I’m using GPL-3.0 when the product targets end-users. We hope people concentrate their efforts around these GPL repositories, but if they decide to go in another direction, at least they have to keep the source open elsewhere. I’m using Apache 2.0 for libraries, giving the necessary freedom developers need to fulfill the requirements of their solutions. I’m using MIT for tools that target developers and non-technical people. Here is the distribution:

• GPL-3.0 License
  • Digger
  • Minimily
  • Controlato
  • Pycific
• Apache 2.0 License
  • CSVSource
  • SpitFHIR
• MIT License
  • Liftbox

We reached a point where all the repositories are minimally organized to welcome contributions. This is the result of implementing the RMM Level 1. At this point, we’re ready to pursuit Level 2, which is delivering a minimal viable product. It means a lot of code, in different languages, solving different problems. You’re welcome to participate by writing code, documentation, tests, etc.

NOTE: I recently changed the repositories to refine my portfolio and documented the changes in another blog post.