I read this tweet yesterday and found myself strong agreeing with the author:
I’m having an issue with something. I’m a PM. Was an engineer. I document everything. No one else documents code, architecture, etc. so others have difficulty onboarding to large projects. Colleague says: “We move too fast to document.” I disagree. Am I out of line?
There are a few factors in today’s market that make documentation even more important than ever IMO (especially with serverless apps):
- High turnover of software engineers as devs leave for better opportunities.
- Most devs that you hire won’t know serverless and will have to learn on the job.
- Increasingly teams are working async (different timezones), so won’t always have immediate access to a team member to ask a question that a doc could answer.
Yet I still see documentation being neglected by many teams who wrongly believe (even subconsciously) that speed and quality are a trade-off.
Determining the right-level of documentation is highly context-specific, but there’s a minimal set of docs that I would expect to see in any serious serverless development project with 2+ developers working on it:
- Dev Environment Setup — Detailed instructions on how to setup an individual developer’s environment from scratch (including local and cloud installs) such that everything is built, deployed to the cloud and all tests passing.
- Architecture Overview — What are the key cloud services being used and any interactions with third party services. What parts of the architecture are deployed together and which are separate?
- Release Process — What’s the branching model (e.g. trunk-based development) and how does code get from the team’s code repository to test, staging and production environments (CI/CD pipelines, etc).
Ideally these should all exist as standalone markdown files within your Git repo, maybe even embedding some Mermaid diagrams-as-code where appropriate.
I’ve found that having the above documents in place saves a ton of time onboarding new developers.
Indie Cloud Consultant helping small teams learn and build with serverless.
Learn more how I can help you here.
Join daily email list
I publish short emails like this on building software with serverless on a daily-ish basis. They’re casual, easy to digest, and sometimes thought-provoking. If daily is too much, you can also join my less frequent newsletter to get updates on new longer-form articles.