“Are we aiming a little too high with the technical complexity?” I asked that about my own website this month, and the honest answer was yes, but not where I thought. The site is for owners of 10 to 200 person firms who are new to AI. It read as if it were for developers. The instinct was to rewrite sentences. I’d already done that pass. The sentences were plain.
The aiming-too-high came from three structural things a rewrite would never have touched: which subjects dominated the piece count, which pieces were labelled as being for everyone, and which words had leaked from the expert pages onto the introductory ones. The fix was mostly labelling and navigation. Here’s the audit, in the order I’d run it again.
1. Count pieces by subject against where the reader actually is
Roughly three-quarters of my pieces were about software that had already been built. My readers are at “people chat with AI” or “a process changed”. No sentence-level pass fixes a subject mix. Record the gap as what to write next, not as a rewrite, and move on.
2. Check the “for everyone” label
“For everyone” had drifted onto anything written plainly. A security pass, a vault method, a team standards playbook, the build write-ups. Each was clear. None could be acted on without a technical team.
The rule I adopted: a piece is for everyone only if a reader with no technical background can act on it. If acting needs a repo, a database or a pipeline, it’s for the technical audience, however plain the prose. Eleven of seventeen “for everyone” pieces moved to the technical shelf.
3. Find the expert words on the owner-facing pages
Each one stood for a plain question, so replace it with the question. Instrumentation became “would you know if it broke”. Guardrails became “what it can see”. Secret store became “password manager”. “Errors tagged with the version” became “a record of which change was live”. Static review became “a read-through”. Scheduled scanning became “automatic checks”.
The technical term keeps its place inside the collapsed detail or on the technical pages. The owner-facing sentence carries the question.
4. Check where the navigation lets the wrong reader land
The menu and the footer offered the technical shelf one click from the header. The vault, the builds, the topics index. An owner who clicked any of them landed in the deep end and concluded the site wasn’t for them.
Now the technical shelf sits behind one door, the start page for AI-coders, and the menu offers that door instead of the shelf. The home page’s “latest” block filters to the owner audience, and the pinned list swapped a code-review playbook for the one-page policy.
5. Reorder the services by stage
Lead with what a client with no plan needs, then “once there is something to check”, then “later”. No service was cut. The order is the message, and it’s the cheapest change on this list.
The shelf, sorted by situation
The technical shelf itself is now in three tiers named for where the reader is, not how experienced they are. Your first weeks: habits while mistakes are cheap. Shipping inside a company: something is about to be relied on. Running a team or several apps: consistency, memory and upkeep across codebases.
Naming the tiers by skill, beginner and advanced, would have put the wrong people in the wrong tier and insulted the rest. An experienced developer who is new to AI tools starts at the first tier too. The lists under each tier aren’t maintained by hand: each piece carries its tier, and the page builds the shelf from that at publish time, so the lists stay true as pieces are added or relabelled. The technical notes on how are in the vault.
A sorted shelf exposes the thin tier. Four pieces in the first tier against fourteen in the third. That imbalance is the useful output. It says what to write next, and it went into the plan as a dated line.
Two rules I’d keep
Measure before you rewrite, and don’t quote time estimates for the work. “An hour” and “an afternoon” had crept into the site’s own proposals from its own copy. None was measured, and the edits took minutes. Say what a change touches instead: files, structure or words only, reversible, needs the owner’s read.
If your own site assumes the reader knows more than they do, start with the count, the label and the words. Leave the sentences for last. They’re probably fine.