A Guide to Great Project Documentation
We’ve all been there as developers: a bug is found in Production and while debugging you stumble upon a dusty, long-forgotten (but of course mission-critical!) system where the problem seems to originate from. You open up the Readme file to see what the heck it’s about — only to find that there is no documentation, other than the ambiguous name of the repository…good luck! In this article we’ll take a look at how to prevent this scenario and help your Future Self and other developers by adding great documentation to your projects.
In essence the main point of project documentation is asynchronous knowledge sharing. The documentation should enable anyone that starts working with the project to easily understand its purpose, usage and current state and ultimately makes the developer experience better.
To start off, write down the purpose of the system or service in 1–2 sentences, mentioning the most important functionalities and/or problems it solves. This enables readers to immediately get a high-level summary of what the project is about.
For instance, check out this intro from the official Kubernetes repository:
“Kubernetes, also known as K8s, is an open source system for managing containerized applications across multiple hosts. It provides basic mechanisms for deployment, maintenance, and scaling of applications.”
Pretty clear what it‘s about right? Include the same for your project with this basic template, just fill in the blanks using your own data:
The [name of the system / service] is used for [X] to do [Y].
Add this to your Github or NPM project and you’re well underway to great project documentation, but let’s go ahead and look at the other important parts.
Architecture — The high level overview
Your system or service will probably involve some architecture to make it run. Charting this will give the reader a high level overview of the application structure and the parts contained in it. Personally, I use Diagrams.net which is a free, open source diagram (web-)application. They even provide service-icons for all the major cloud platforms like AWS and Azure so you can easily depict anything, from a database to a load balancer.
Using this tool we can make a clear, visual overview where readers can see the overall system structure at a glance. This overview will also come in handy if the project needs to be restructured or updated in the future and can be the base for your (architecture-)meetings.
Dependencies
If your system or service is part of a bigger ecosystem (for instance within a company) there are probably dependencies to take into account that are crucial for to know about before making changes. Providing links to these repos might be a life-saver one day. You can even opt to include these in the architecture overview, just be sure keep the project-boundaries and -responsibilities clear.
Decisions
Starting a new project usually comes with stakeholders requesting a feature based on acceptance criteria and requirements. These constraints have a big impact on the decisions we make and these decisions, in turn, impact the system: using framework X instead of Y, choosing a specific software pattern or, even more high level, the programming language. Briefly documenting why decisions were made can save you and others a lot of headaches later on when stakeholders request new, snazzy features or other teams take over the project.
Business logic
It’s not a given, but in general every company has its own ‘language’ and, sadly, often its own acronyms (the latter famously disliked by Elon Musk at SpaceX, prompting him to send an e-mail that “Acronyms Seriously Suck (ASS)”).
Explaining some of the terms that are crucial for the project can help other developers and stakeholders a lot. Example: I worked on a project where it was important to know the difference between an ‘offer’ and a ‘promotion’, at first glance they seem interchangeable but in our context both had a different meaning and implication.
The Setup
The above parts were all giving information about the project, but now your readers want to get their hands dirty and set up the project on their local machines to develop new features. Giving a clear setup guide will make their lives a lot easier — and yours as well as no one will be coming by your desk to ask for help! Clearly write out all the steps necessary to get the app running, from installing NPM dependencies, seeding databases to generating access keys. If you used an external framework library, give a short summary for the setup and refer to the external documentation. That way, even if the external framework changes or gets deprecated your reader will still be able to set up the system.
Quality attributes
Next to writing working software, one of our most important tasks is keeping the quality high. Guarding that quality is important and we want new contributors to know about this as well, so do briefly mention it in the documentation. Are there automated tests that will run in a CI/CD pipeline and need to be updated when new features are introduced? If you built a webapp you probably check the compatibility with a tool like Browserslist that needs periodic updates. Are there guidelines for codestyling through linters and formatters devs need to set up in their IDE? Is the system being monitored for downtime and critical bugs? If so, who gets the notifications? There is nothing more useless than having downtime-detection set up but no one receives the notifications. Don’t let the user find out first your application is down.
Closing
At the end of the day no one wants to read excessive documentation, so keep it clear and to the point. Focus on the essential information for someone that wants to understand what the project is about and enable them to easily work on it. This will save everyone a lot of headaches, so after reading this article please consider your next project ‘unfinished’ when there is no documentation included yet!
