Six years into client work, my worst outages were not missing tests. They were missing notes. Why this app. Why this model. Where the staging key lives. What we promised not to automate.
Project documentation on day one sounds like bureaucracy. It is actually a gift to future-you in Karachi at midnight when the merchant says the bot started inventing shipping rates.
The three docs that pay rent
I no longer wait for “clean up the README later.” I start three thin files — even if they are ugly.
1. Decision log (not a novel)
One page. Dated bullets:
- Chose theme X over Y because of section support and app footprint
- Used metafields for care instructions; metaobjects for size charts
- Default model: mini; escalate to 4o on claim-check failure
- Explicitly out of scope: auto-refunds without human approval
When a stakeholder asks “why didn’t we use the popular app?”, you answer from the log instead of reconstructing a Slack archaeology dig.
2. Credentials and environments map
Not the secrets themselves — the map:
- Where production keys live (password manager / host secrets)
- Which store is staging versus production
- Callback URLs and which app install belongs to which shop
- Who can rotate what
I have lost hours because a “temporary” API key lived only in one laptop .env. The map would have said “rotate in provider dashboard; update host env; redeploy worker.”
3. The “why this model / why this pipeline” note
For AI features, write:
- Tokens assumed per request
- Daily volume assumed
- Fail-closed behavior (refuse, handoff)
- Logging and PII rules
- Eval set location
This is the note that stops a well-meaning teammate from “temporarily” pointing production at the most expensive model to fix a demo.
What I skip (so the docs stay alive)
I do not write 40-page Confluence epics nobody reads. I do not screenshot every settings page. I do not duplicate Shopify’s own docs.
I do document the weird parts: the Liquid snippet that must load before app X; the webhook that retries twice and must be idempotent; the brand banned-word list; the timezone the weekly job assumes.
A day-one checklist I actually use
Before the first meaningful PR merges:
- Decision log started with the kickoff choices
- Environments named; secrets mapped; no secrets in git
- README with how to run locally and how to deploy
- For AI: cost assumptions and refuse/handoff behavior
- For Shopify: theme vs app boundaries and metafield namespaces
- Contact path for the human who owns content truth (policy, legal, shipping)
Ten minutes each. Cheaper than a war room.
Docs as part of the product narrative
Side projects get the same treatment. MetaGrid / BulkFix-style tools need a “what we will never do” section so feature requests do not dissolve the wedge. VisaChamp-style document QA needs a clear statement on refuse-when-empty so nobody “improves” it into a guessing machine.
Public playbooks and private client docs share a tone: practical, dated, no fake precision.
When the client hates documentation
Some merchants pay for outcomes, not markdown. Fine. The docs are still for the builders. I fold the decision log into the proposal appendix and the handoff package. They experience it as professionalism: fewer repeat questions, cleaner change requests, faster onboarding if another developer joins.
If a change request contradicts a recorded decision, we update the log on purpose — not by accident in production.
Decision logs that survive Slack
Slack is where decisions happen and where they go to die. I copy the final call into the log the same day: date, decision, alternatives considered, owner. No essay. If a thread is long, I link it once. Future disputes get a document, not a scavenger hunt.
Credentials map without putting secrets in git
The map names systems: Shopify stores, OpenAI/Anthropic/Google projects, hosting, email, vector DB. It points to the password manager items or host secret names. Onboarding a contractor becomes “here is the map” instead of “I’ll paste keys in chat.” Pasting keys in chat is how day-one docs get rewritten as incident reports.
Runbooks for the 3 a.m. failures
Short runbooks beat perfect wikis:
- Bot returning empty: check retrieval status page, provider status, last index time
- Catalog job stuck: queue depth, rate limit metrics, idempotency replay steps
- Theme app conflict after install: disable embeds checklist
Each runbook lists what “good” looks like after recovery. I write them when the feature ships, not after the second outage.
Handoff package for clients
At project end I deliver: decision log, credentials map (with rotation advice), model/pipeline note, and a 30-minute loom or live walkthrough. That package is part of the product. Merchants remember the calm handoff when something breaks six months later and they need to hire the next developer.
Teaching the team to update docs
Docs die when only I touch them. In the kickoff I assign owners: merchandiser owns banned-word list; engineer owns env map; I own cost assumptions until handoff. Tiny ownership beats a generic “everyone update the wiki” plea.
Templates I leave in the repo
/docs/DECISIONS.md, /docs/ENVIRONMENTS.md, /docs/AI_PIPELINE.md, /docs/RUNBOOKS/. Four paths. New engineers find them without asking Slack. If the client prefers Notion, I mirror the same four pages and link from the repo README so the canonical paths stay guessable.
I also leave a “last verified” date on the environments map. Stale docs are dangerous; dated docs are debatable. Debate is fine. Mystery is not. Day-one documentation is really day-one habits — five minutes when something changes beats a heroic rewrite later.
Screenshots age; decisions age slower
I used to paste admin screenshots into docs. Themes update; apps move buttons; screenshots lie within a month. Prefer durable references: metafield namespaces, API version pins, model names, and the reason for a ceiling. If a UI path matters, describe it in words plus the date you verified it.
Same for AI prompts: store the canonical prompt in the repo with a version comment. ChatGPT history is not documentation. When a merchant asks why the bot refused a refund question, you want the prompt version and the refuse rule, not a memory of a Tuesday experiment.
A note on tone
Write docs like you write proposals: plain, dated, no fake precision. Future-you is busy and slightly annoyed. Clever prose does not help at midnight; clear next steps do.
Write the note you will search for later
The documentation I wish I had always fits one screen and answers a panicked question. Start those files on day one while the reasons are still obvious. Future-you is a stakeholder too.
If you want a build that includes handoff docs, cost ceilings, and Shopify-aware AI behavior — not just a deployed surprise — that is how I like to work.