❯ 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
- https://www.aitrends.com/ai-world-government/promise-and-perils-of-using-ai-for-hiring-guard-against-data-bias/
- https://www.aitrends.com/ai-world-government/advance-trustworthy-ai-and-ml-and-identify-best-practices-for-scaling-ai/
github.com/your-org/widget-service.gitwidget-green.example.com/health- https://www.aitrends.com/ai-insider/novelty-in-the-game-of-go-provides-bright-insights-for-ai-and-autonomous-vehicles/
- https://www.fastcompany.com/91638740/allison-ellsworth-jetty-launch