Use cases

Engineering Documentation in Google Docs: Runbooks, ADRs and Onboarding

A folder structure for engineering docs in Google Drive, runbook and ADR templates to copy, and the fixes that make Docs comfortable for engineers.

Eric Dunaway
Eric Dunaway
Spaceli
5 min read

Code documentation belongs next to the code, in READMEs and docstrings. Everything around the code (runbooks, architecture decisions, onboarding, processes, postmortems) is written for people, and many engineering teams already write it in Google Docs, where product, design and support can read and comment too.

This guide gives you a folder structure for engineering docs in Google Drive, templates for the two documents teams most often get wrong (runbooks and architecture decision records), and the fixes that make Docs comfortable for engineers: code blocks, links and search.

A structure for engineering docs

Engineers look for documents by what they are, so the type of document is the top-level folder.

Engineering folder
Engineering (shared drive)
├── 00 Start here
├── 01 Onboarding
│   ├── Dev environment setup
│   ├── How we ship
│   └── First week tasks
├── 02 Architecture
│   ├── System overview
│   └── Decision records
├── 03 Runbooks
├── 04 Processes
│   ├── Code review
│   ├── Releases
│   └── On-call
├── 05 Specs and RFCs
├── 06 Postmortems
└── 99 Archive

Name decision records and postmortems with a number or date first ("ADR-012 Move to Postgres", "2026-11-03 API outage") so they sort in order. Templates for other teams are in our Google Drive folder structure for teams. Specs usually start from a product brief; here's a PRD template for Google Docs.

Two templates

Runbook

A runbook is read at 3 a.m. by someone who didn't write it. Keep it short, specific and copy-pasteable.

Runbook template
# Runbook: [Service or alert name]

Owner: [team]  ·  Last tested: [date]

## When to use this
The alert or symptom that brings you here.

## Impact
What users see while this is happening.

## Check first
1. Dashboard: [link]
2. Logs: [command or link]

## Fix
1. [Exact step, with the command to run]
2. [Exact step]

## If that didn't work
Who to escalate to, and how.

## Afterwards
What to record, and where.

Architecture decision record (ADR)

An ADR captures why a decision was made, so the next person doesn't have to guess or relitigate it.

ADR template
# ADR-[number]: [Decision in a few words]

Status: Proposed / Accepted / Superseded by ADR-[n]
Date: [date]  ·  Deciders: [names]

## Context
The problem and the constraints.

## Options considered
1. [Option]: pros, cons
2. [Option]: pros, cons

## Decision
What we chose, in one paragraph.

## Consequences
What gets easier, what gets harder, what we'll revisit.

For processes outside engineering, such as releases signed off by other teams, the same approach works as an SOP in Google Docs.

Making Docs work for engineers

Engineers' usual complaints about Google Docs are fair: code looks wrong, finding the right runbook takes too long, and docs are hard to reuse elsewhere. Spaceli fixes these without moving your docs out of Drive.

  • Real code blocks. Code written in Google Docs shows with automatic syntax highlighting for 16 languages, a language label and a copy button. Inline code with backticks works too.
  • Callouts for what matters. Mark the dangerous step in a runbook as a Warning or Danger callout, right in the Doc.
  • Fast search. Cmd+K finds titles instantly and searches the full text, so the right runbook is seconds away during an incident.
  • Links to any heading. Link straight to "Rollback" in the release runbook; links between docs open inside the space.
  • Copy as Markdown. Copy any page as clean Markdown, with headings, tables, code and callouts, for READMEs, pull requests or AI tools.
  • Diagrams and walkthroughs. Embed Miro or Whimsical diagrams and Loom walkthroughs next to the text.
  • Light and dark mode. Docs adapt to the theme, which engineers tend to appreciate.

FAQ

Should engineering docs live in Google Docs or in the repository?

Both. Docs that change with the code (API references, setup steps tied to a version) belong in the repository. Docs written for people across teams (runbooks, decisions, processes, postmortems) work well in Google Docs.

How many ADRs should a team write?

One per decision that would be expensive to reverse or that people keep asking about. Most teams write a few a quarter.

How do we keep runbooks current?

Test each runbook when its alert fires or once a quarter, and update the "Last tested" date. A runbook nobody has tested is a guess.

Eric Dunaway
Written by Eric Dunaway

Writes about wikis, documentation and how teams keep their knowledge easy to find.

Share

Your knowledge base is already in Google Drive.

Give your team a better way to organize, find, and share knowledge. Keep your documents right where they are.

Start for Free

Free during the beta. Get started in about a minute.

Spaceli only accesses the folders you choose.