A minimal set of documentation for your serverless project

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):

1. High turnover of software engineers as devs leave for better opportunities.
2. Most devs that you hire won’t know serverless and will have to learn on the job.
3. 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.