21 Jul 2020

3 minute read

Open Source Software and especially large projects have a few defined standards that are used to promote welcoming new contributors and ensure a healthy collaborative environment like for example,, and issue/pull request templates.

Despite this, even in popular projects, there is a disconcerting lack of guidance on the actual structure of the software and its inner workings.

For example, as a part of the open source Google Code-in event, last winter I started contributing and still contribute to Public Lab, an environmental community that develops environmental software.

This forum’s code base is relatively large, especially for an open source beginner. It has about ~25 controllers, ~30 models and a very complete testing suite with functional, unit and system testing all automated with Travis.

But I took some time and read through the code to understand how the different bits and pieces of the app interacted, and grew to a confident level with some parts and at least an abstraction of understanding with the others. I luckily also had the help of my mentors who answered my questions during this process.

Obviously, this mentorship is often unavailable and new contributors have to scrutinize the code base on their own, and try to come up with a vague understanding of the components that will prevent them from creating a breaking change in another part of the app.

For example, in other industries, usually physical blueprints serve as this stepping stone to provide an overview of how the product works as a whole and yet it’s often missing in software engineering.

Let’s take an example. I’ve been getting into the Crystal programming language as a faster, type-checked alternative to Ruby. I really enjoyed the language and wanted to contribute and understand the code. I checked out their and it provided me with mostly a social / collaborative overview of where I can discuss issues or ideas, where I can ask questions, etc… What it did not provide was a technical overview of how the code is structured, the way it all comes together and its tech stack.

Putting this information would be helpful to not put off curious contributors that want to learn and develop a higher-level understanding of how the project works.

These frustrations are pushing me to propose a new “standard” for welcoming open source contribution, an file, that would work on top of to inform on:

It’s easy for the creators of a project to represent in their minds the way all the pieces of the project come together, but transcribing these pieces together into a document would be extremely beneficial, not only to teach others but also to clarify and renew one’s own understanding of their own code base.

If you have any other ideas for additional information it could contain, please comment! I think this could be incredibly useful in general to make access to open source projects easier and lower the learning curve.