❯ Documenting a Process: Stop Dithering, Just Ship It (The Right Way)

by Jonas Reyes — the builder's desk, Side Quest Studios
November 10, 2026

Alright, let's cut the crap. You’ve got a process, it works, and you can run it blindfolded at 3 AM. Great. Now document it so someone else – anyone else – can run it without waking you up. I've seen more "AI-powered hiring platforms" promise the moon and deliver a black hole of bias than I've seen correctly documented internal procedures. AI trends report on hiring bias confirms it: people over-complicate simple things and then wonder why it breaks. This isn't rocket science, but if you treat it like a vendor's pitch deck, it'll blow up in your face.

The Goal: No Heroics, Just Reproducibility

Here’s the deal: the goal of documentation isn't to write a novel. It's to make the process repeatable by a competent individual who has never seen it before. Think of it as a bash script for humans. Every single step must be explicit, every command copied and pasted. Your "institutional knowledge" is a liability if it's trapped in your head. No, you don't need a fancy "AI-driven knowledge base" that promises to "advance trustworthy AI" DOE on Trustworthy AI. You need a text file.

I once spent four hours at 2 AM trying to figure out why a critical cron job wasn't running after a server migration. Turns out, the previous admin had a habit of setting HISTFILESIZE=0 and never documented the one-off PATH export he'd put in his .bashrc for that specific script. A single line in a README would have saved me half a night. Don't be that guy.

The Absolute Minimum: README.md and a Script

Forget the enterprise wiki, the SharePoint monstrosity, or the "dynamic, interactive knowledge portal." You need a README.md file in the root of your project directory. That's it. This isn't some groundbreaking insight, it's just how we've always kept things from imploding.

For any process that involves more than two commands, write a script. Seriously. If you can't automate it entirely, automate the parts that are repetitive, prone to error, or require specific flags.

Here’s the structure for your README.md:

# Process Name: Deploy New Widget Service

## 1. Overview

Briefly explain *what* this process accomplishes and *why* it exists.
Example: "This process deploys a new instance of the Widget microservice to production, ensuring zero downtime via Blue/Green deployment strategy. It's run after a successful QA regression."

## 2. Prerequisites

List *everything* someone needs before they start.
- **Access:** SSH access to `prod-bastion.example.com`
- **Tools:** `kubectl`, `helm`, `aws-cli` (v2.x)
- **Environment Variables:**
    - `AWS_PROFILE=widget-prod`
    - `KUBECONFIG=/path/to/kubeconfig-widget-prod`
- **Dependencies:** Python 3.9+, `boto3` installed (`pip install boto3`)
- **Credentials:** JIRA API token (for step 5, linking ticket)

Be specific. Don't say "AWS CLI". Say `aws-cli` v2.x. Give the command to check: `aws --version`.

## 3. Steps

This is the meat. Numbered list. Every command. Every flag. No shortcuts in your head.

1.  **Pull latest code:**
    ```bash
    git clone https://github.com/your-org/widget-service.git
    cd widget-service
    git checkout main
    git pull origin main
    ```

2.  **Build Docker image:**
    ```bash
    export IMAGE_TAG=$(date +%Y%m%d%H%M%S)-$(git rev-parse --short HEAD)
    docker build -t your-registry.example.com/widget-service:$IMAGE_TAG .
    docker push your-registry.example.com/widget-service:$IMAGE_TAG
    ```
    *Note: Replace `your-registry.example.com` with the actual registry URL.*

3.  **Update Helm chart values:**
    Open `helm/widget-service/values-prod.yaml` and update the `image.tag` field:
    ```yaml
    image:
      repository: your-registry.example.com/widget-service
      tag: <NEW_IMAGE_TAG_FROM_STEP_2>
    ```

4.  **Deploy with Helm (Blue/Green):**
    ```bash
    helm upgrade --install widget-service helm/widget-service \
      --namespace widget-prod \
      --values helm/widget-service/values-prod.yaml \
      --set ingress.host=widget-green.example.com
    ```
    *Wait for Green deployment to be healthy:* Check `kubectl get deployments -n widget-prod`.

5.  **Run smoke tests (critical):**
    Navigate to `https://widget-green.example.com/health` and verify HTTP 200.
    Run automated smoke tests:
    ```bash
    python3 scripts/run_smoke_tests.py --env green
    ```

6.  **Switch Ingress to Green (traffic shift):**
    Open `helm/widget-service/values-prod.yaml` again and update `ingress.host` to `widget.example.com`,
    and set `ingress.color` to `green`.
    ```yaml
    ingress:
      host: widget.example.com
      color: green # or 'blue'
    ```
    Then apply the change:
    ```bash
    helm upgrade --install widget-service helm/widget-service \
      --namespace widget-prod \
      --values helm/widget-service/values-prod.yaml
    ```
    *Verify traffic:* Check `nginx-ingress-controller` logs for traffic to the new pods.

7.  **Post-deployment verification:**
    - Check Grafana dashboards for `widget-service` for 15 minutes.
    - Confirm no new errors in Sentry.
    - Close JIRA ticket `WIDGET-1234` with a link to the deployment runbook.

## 4. Rollback Plan

What happens if it all goes to hell? Don't gloss over this.

1.  **Identify previous stable image tag:** Look in Git history for `helm/widget-service/values-prod.yaml` before the current deployment.
2.  **Revert Helm chart values:** Update `image.tag` and `ingress.color` to the previous stable values.
3.  **Redeploy with Helm:**
    ```bash
    helm upgrade --install widget-service helm/widget-service \
      --namespace widget-prod \
      --values helm/widget-service/values-prod.yaml
    ```
4.  **Verify Rollback:** Run smoke tests on the reverted version.

## 5. Troubleshooting / Common Issues

"What if `kubectl` is not found?" "What if `docker push` fails?"
- **`Permission denied` on `docker push`:** Ensure your `~/.docker/config.json` is configured correctly for `your-registry.example.com`. Run `aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin your-registry.example.com`.
- **Helm upgrade hangs:** Check `kubectl get events -n widget-prod`. Pods might be failing to start due to resource limits or image pull issues. Look at `kubectl describe pod <pod-name> -n widget-prod`.

## 6. Contact / Escalation

Who to call if the world is ending and the README didn't help?
- **Primary:** @terminalking on Slack
- **Secondary:** On-call rotation for `#widget-team` PagerDuty

The "But I Use a GUI!" Cop-Out

I get it. Some of you are stuck clicking buttons in a cloud console or a "low-code" platform. Fine. If you must use a GUI, take screenshots. Each step. Draw red boxes around what needs clicking. Label everything. Then, for the love of all that is holy, put those screenshots in order in your README.md. Use asciinema for CLI if you need to show interaction, but plain text is better.

I've had conversations where people tried to explain "just click the big green button." Which big green button? In which tab? After which dropdown? Specify it: "Navigate to EC2 -> Instances, select i-0abcdef12345, click 'Actions' -> 'Instance State' -> 'Reboot'." Don't make people guess. Your documentation should be so clear a junior engineer could execute it without supervision, not even thinking about "novelty in the game of Go" AI in Go.

Validate Your Documentation: The Acid Test

Here’s the shortcut to knowing if your documentation is any good: give it to someone who has never done the process before. Not your co-worker who sits next to you and knows half your shortcuts. Someone fresh. A new hire. An intern. Tell them to follow it, step by step, without asking you any questions. If they get stuck, fail to complete it, or worse, break production, your documentation is bad. Fix it.

This is not a "nice-to-have." This is how you avoid burning out, how you enable your team, and how you scale. It’s how you build real systems, not just theoretical ones that only work when you're personally holding them together with duct tape and caffeine. Allison Ellsworth didn't sell Poppi for $2 billion by having undocumented processes Allison Ellsworth's new venture. She built a system. You need to do the same.

Stop overthinking it. Stop waiting for the perfect tool. Grab a text editor, open README.md, and start typing. Now.

by Terminal King — the terminal, Side Quest Studios

References

💬 Discuss this article in the community — 0 replies →
Comments live on community.sqs.chat — one thread per article.