Photo by Annie Spratt on Unsplash

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

    Architecture & Process Review

    Built a serverless app on AWS, but struggling with performance, maintainability, scalability or DevOps practices?

    I can help by reviewing your codebase, architecture and delivery processes to identify risk areas and their causes. I will then recommend solutions and help you with their implementation.

    Learn more >>

    🪲 Testing Audit

    Are bugs in production slowing you down and killing confidence in your product?

    Get a tailored plan of action for overhauling your AWS serverless app’s tests and empower your team to ship faster with confidence.

    Learn more >>