Why I wrote 40 design documents before building this site
My first blog was a few HTML, CSS and JS files. Later I installed a blog engine (Ghost), but it held a single “Coming soon” post, the language was set to English, the time zone to UTC, and member sign-up was open without any mail setup. An entrance was open that did not actually work.
Design first
So before writing code I decided in writing what to build: product requirements, information architecture, design system, data model, API, permissions, security, search, AI, deployment, recovery… it became 40 documents.
Then compare
With only a design it is easy to throw away things that already work well. So I put the running systems next to the design and judged each item.
| Verdict | Meaning | Example |
|---|---|---|
| Adopt | As designed | Static generation, site search |
| Adapt | Merge both or fit to the environment | Approval via GitHub PRs instead of a separate DB |
| Keep | The current system is already better | The chat’s search and safety engine |
| Defer | When conditions appear | Comments with social login |
For example, the design asked to pick a new search provider for Ask AI, but the chat already had engine fallback, personal-data removal and internal-network blocking. There was no reason to rebuild it.
Principles kept
- Posts live in Git; publishing happens via release tags. If something breaks, the previous tag is back within a minute.
- A page with no translation is never silently replaced by the original language.
- Security headers are applied once at the front, not per app.