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.

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.

    View Emails Archive

    ☎️ Serverless Clarity Call

    Need quick guidance on a specific issue on your AWS serverless project? Or just wondering where to start with serverless?

    Book a call and ask me anything.

    Learn more >>

    🛫 Serverless Launchpad

    Ready to start building your new AWS serverless project but need help with getting everything setup?

    The Serverless Launchpad is a done-for-you DevOps service installed in under a week. You get a leading-practice multi-account AWS environment, a scaffolded codebase and architecture including the common AWS serverless services, isolated cloud environments for individual developers, automated delivery pipelines right through to production and much more. Everything is IaC, extensively documented and handed over to your developers.

    Learn more >>