Start Here: Building the Tool While Using It
By John Hardy
January 9, 2026 | Series: genesis
This project exists to test a new model of software development and content production in public. The repository is both the lab and the record, and the system I am building will publish the discoveries that come out of its own construction. If you want the map of how the system thinks, treat this series as a lab notebook with working notes and decisions in view. I want readers to see the system forming alongside the result.
The first content is the documentation process itself, so I write while I build and treat the conversation and decisions as raw material with constraints and contradictions kept visible. The Q/A process I am working out here is the real work, and it becomes the content. Each entry shows a decision while it is still forming, before it hardens into tooling.
Over time, this back-and-forth will harden into scripts as the workflow stabilises and the content aligns with the system it describes. The point of doing it in the open is that the system proves itself by publishing its own formation. The diary becomes the tool because each change leaves a record I can test and reuse.
I minimise imports and treat third-party tools as a last resort. When a problem fits in a small script, I write it and keep it in the repo so the implementation stays visible. When the problem is larger than that, I import a library and document the specific gap it fills.
On the publishing side, I am aiming for the most boring convention that still works: a home page index with the newest post at the top. Each post also gets a dedicated article page with a stable permalink. That is the shape of the site I want to live inside. It lets me read the archive as a plain list without extra machinery. It also keeps the build simple enough to inspect.
To follow the build as it forms, read the genesis series in order, starting here. After this post, read Blog Philosophy. Next, read A Blog That Is Also the Build System and continue forward through the series.
Related posts: Blog Philosophy, A Blog That Is Also the Build System.
Why I'm Building This in Public
By John Hardy
January 9, 2026 | Series: genesis
I'm building this in public because writing details down changes how I think. When ideas stay private they remain vague and provisional. Writing for an imagined reader sharpens the ideas and shows the gaps as decisions harden on the page.
This repository is where I'm working decisions out and where those workings live. The notes and specs sit beside the code they shape, with half-decisions and revisions kept close by. They stay inside the process, present while I shape the code.
The writing is one of the tools I'm using to build the system. It affects the choices I make and keeps the work accountable because it has to be readable to someone besides me. One concrete example: when I wrote down the rule that templates should remain pure HTML, it stopped me from adding conditional logic in a rush. That single paragraph forced me to move selection into named queries and keep the rendering mechanical, which is now a fixed constraint in the build.
A central concern in the experiment is how AI fits into this. I want AI as a constrained collaborator with clear boundaries about authority and intent, along with what I allow to change. Those constraints preserve the shape of the work while still letting me use speed and advantage when they help. The blog that will appear here comes from the project and follows the same rules, so templates and queries show up alongside build scripts and deployment because the writing needs them. Another example came from tagging, where writing down the normalisation rule forced me to rename a handful of tags and rebuild the indexes so the archive stayed coherent and kept near-duplicates in one place. If you want the companion piece on pace and voice, read Writing Fast Without Writing Sloppily.
I still work out my position, and I take my time with it. This is an attempt to think carefully and design slowly while leaving a readable trail behind. The trail should stand on its own, even if I am the only person who ever reads it end to end.
Tags: writing, ai
Writing Fast Without Writing Sloppily
By John Hardy
January 9, 2026 | Series: genesis
Writing quickly matters to this project because without it I'd slow down and publish less. The pace drives the experiment because ideas form in real time and I make decisions under pressure, so the value is in capturing them while they're still alive. That creates tension: speed pulls me toward shortcuts and familiar phrasing that drain the work of voice.
It's easy to slide into that as certain phrases arrive fully formed and sentences drift into explanation while leaving description behind. Paragraphs climb into commentary about the writing. Language has grooves, so when I'm moving fast I let the wheels fall into them.
Automation helps here, even though it's awkward. I don't believe there's a reliable way to algorithmically judge good writing, and I'm not trying to invent one. What I do think is possible is to detect laziness. I watch for repetition and familiar scaffolding, then for verbal tics that appear when attention drops or when a phrase announces an idea before it arrives because those patterns show up quickly.
The prose-lint script most often catches short scene‑setting lines that do no work. It also flags contrast framing that drifts into meta narration. It flags tidy lists of three that flatten nuance. Those are the signals that my attention slipped and the prose started to coast.
One example I keep seeing is a scene-setting line that gestures at the topic and then stalls. Draft: "This section is about speed and quality in writing." I rewrite it into a concrete decision. A revision like "I write fast to capture decisions while they are fresh, then slow down to keep the voice intact" turns an announcement into an argument.
This project will involve writing local scripts that scan prose and score it for those habits. The scripts are friction: no rewrites, no house style, just a mirror. If a draft trips too many signals, that's my cue to slow down and look again because the tooling doesn't decide what's good.
There's something slightly perverse about using code to guard against formulaic writing, but it fits the larger theme here. Staying awake is the point, so fast writing only helps when it still sounds like someone thinking without the shape-filling feel of a system. A bit of automation that keeps me alert while I move quickly feels like a fair trade.
In case it wasn't obvious, yes of course I will be employing AI to help me write and help me review my text content. Learning how to do this in a timely manner without producing soulless slop is one of the big challenges of this project and one of the design goals is to help me as the writer use the assistance of AI without ever putting it in the driver's seat.
Steve Jobs once said "the computer is like a bicycle for the mind". The way I've been thinking about it lately, AI is like an e-bike for mine. Let's hope it doesn't drive me into a ditch!
Tags: writing, automation
A Blog That Is Also the Build System
By John Hardy
January 12, 2026 | Series: genesis
I built the repository to be the blog and the build system with the record of how the build changes kept in the same place. That sounds neat as a concept, but it is also a practical choice. If I keep the content in a single place and put the scripts that shape it in the same place, I can read the whole system like a diary where the log of work becomes the work and the writing lives inside the software taking shape.
This idea changes how I think about content. A post is a folder with a Markdown file and nearby assets, plus a small amount of metadata that makes indexing possible. The folder tree is the public rhythm of the blog. Dates become paths and months become folders, so each post sits as a leaf in the tree. I can point at the layout and show how the site thinks.
It also changes the role of automation. I rely on a handful of scripts that are obvious when I read them, because that makes the system legible to me and to the AI that maintains it. The scripts handle repetition, and the repo holds the permanent record. When the AI adds a script, it becomes an event in the diary and the change itself becomes content so the build system learns in public.
The same principle applies to templates, which are plain HTML and only stamp content into a page. Queries decide what exists, and those queries live beside the content they select. That is the heart of this approach. The data and selection stay visible, and the render stays visible too. When I say that the blog is the build system, I mean that the entire path from idea to page is traceable inside one repository. If you want to inspect how the system works, you can read the archive and follow those decisions in plain sight.
Pick any entry and follow its folder path to trace the decision trail that produced it.
I do this because I want to write about building the blog while I build it. The first posts will be about the system that is learning to publish the posts. I am comfortable with that because I treat the system as a living artifact. The repo is the journal, which becomes the site and the build.
Blog Philosophy
By John Hardy
January 12, 2026 | Series: genesis
I write this down early because it is the anchor I will keep returning to and the blog only works if it lets me publish day to day technical work without friction while AI drafts alongside me and I keep control of the final voice. That constraint is the condition that makes the rest of the system worth building.
The centre of it, for me, is the web itself. I keep coming back to classic HTML and the original web idea from Tim Berners-Lee. A document should read cleanly in source and still make sense without scripts, and a link should act as a stable address with no runtime dependency. I want this site to feel like the early web did when it was a network of human readable documents where the page is the page and the URL means what it says.
That stance forces decisions about durability and access. Accessibility and internationalisation are not optional if I want the site to last, so headings and landmarks must make sense to assistive tools and links must remain clear. Text and layout choices cannot collapse when language or fonts change, or when the reader never uses a mouse. Performance and cacheability live in the same layer. Pages need to load fast on slow networks and stay responsive on old devices.
Discoverability sits beside all of that, so clean URLs and meaningful titles should show their intent without JavaScript. Indexable pages should do the same work to show intent. SEO and AI visibility should follow from clear structure and plain metadata, without overlays or tricks. I will use unobtrusive JavaScript where it helps navigation, but I keep the baseline page intact with classic HTML as the foundation.
The tooling has to match that posture, so I favour a minimal toolchain and native JavaScript while keeping the feature scope tight. I will add theming and user settings only when they serve reading.
This spec should grow by addenda so the trail stays visible. I am writing the blog while building the blog, and that loop stays central. A philosophy should show in the site, and the site should reveal any drift. If I drop these constraints, the archive loses its promise and the project fails its own test. Tags: philosophy, web
