I maintain a single HTML file as an architecture board for the product I'm building. Definitions, data models, API surface, routes, changelogs, postmortems. One file, opens in a browser, shows the state of things at a glance.
I've been using it to stay oriented while developing Tanso, and it's been useful enough that I wanted to share it in case anyone else has been thinking along the same lines.
The origin was simple: I kept asking AI tools to generate structured documents (ERDs, changelog tables, postmortem writeups) and discarding them after a single look. But the output was already organized. The data was already there. The only waste was starting from zero every time.
So I stopped starting from zero and made a template: human-docs.
What's in the repo
template.html Empty scaffold with section markers. Fork and fill.
PROMPT.md Instructions for any AI tool to generate or update the doc.
example.html Cal.com's architecture, fully filled in.
How it works
Point any AI tool (Claude Code, Cursor, Codex) at your codebase with PROMPT.md as the prompt. It fills in the template. Open the result in a browser.
When something changes, you don't rebuild the whole file. The template uses <!-- SECTION:name --> markers so updates are surgical. The AI edits only the sections that are stale, leaves everything else intact. Similar to how you'd review a git diff: only what actually changed.
Over time the file compounds. Each deploy adds a changelog entry. Each bug adds a postmortem. Each migration updates the ERD. The document gets more useful the longer you maintain it.
The sections
| Section | Purpose |
|---|---|
| Definitions | Clarify overloaded or ambiguous terms in the codebase |
| Data Model | Tables, relationships, ERDs grouped by domain |
| Pages & Routes | Every user-facing route and what it does |
| API Surface | Endpoints grouped by domain |
| Changelog | What shipped, filterable by type |
| Postmortems | What broke, root cause, fix, prevention rule |
Postmortems are the most valuable section. Changelogs record what happened. Postmortems record what not to do again.
Why HTML
HTML is self-rendering. Open it in any browser, no preprocessing needed. And because it's structured markup, an AI agent can parse it and update individual sections without regenerating the whole document. It serves both audiences (human readers, AI agents) without needing two versions of the same information.
What I'm actually thinking about
The template is the lightweight part. The more interesting part is the questions behind it.
As AI accelerates execution and one person takes on more, I think the constraint increasingly becomes the human context window. Not writing the code, but keeping track of everything across workstreams. Having a single page where I can see the architecture of a project without reconstructing it from memory has been more valuable than I expected.
And that opens up some directions I keep coming back to:
What if this auto-updated on every commit? A git hook diffs the changes, maps them to sections, and the doc stays current without anyone prompting it.
What if it replaced tools like Swagger or TypeDoc instead of sitting alongside them? The AI is already reading your codebase to fill sections. It can generate API references in the same file, next to the architectural context those tools never capture.
Is HTML even the right format long-term, or just the right format for now? It's self-rendering and structured enough for agents to parse. But if other tools need to consume the data downstream, maybe the source should be structured data with HTML as one view.
I don't have answers to these yet. But I think the questions are worth thinking about, and I wanted to put this out there in case anyone else has been working through the same stuff.
Repo: github.com/katrinalaszlo/human-docs
Open example.html to see what a filled-in doc looks like.
Top comments (0)