Simon Moxon

Building - user facing documentation that writes itself

[Simon Moxon @simonmoxon]

Ten good articles will not make your help centre feel complete. They make it useful, which is a different and more achievable goal.

Complete is a feeling you chase forever. Useful is a bar you can clear this week.

[Simon Moxon @simonmoxon]

@thsottiaux As seen by me yesterday

[Simon Moxon @simonmoxon]

Anyone selling you an "AI SEO audit" with a score out of 100 has invented the score.

Nobody knows exactly how AI retrieval works.

The useful bit is simpler: write clearer docs. If the AI angle is bollocks, you still win.

[Simon Moxon @simonmoxon]

Title your support article with the exact error message. Word for word. The literal red string the user is staring at, not a tidy concept.

People do not search for ideas. They paste the error in front of them. That page beats any general troubleshooting guide.

[Simon Moxon @simonmoxon]

The first pages a cautious buyer reads are about your money, your data, and how hard it is to leave.

Those are the pages founders write last, or never. We build the feature tour first and treat the exit as an afterthought.

Read your help centre in a nervous buyer's order.

[Simon Moxon @simonmoxon]

Pick your ten most important product tasks.

Ask three AI assistants how to do each one.

Log: right, vague, invented.

That table probably tells you more about your docs now than the traffic graph does.

[Simon Moxon @simonmoxon]

The case for writing docs for machines isn't that it definitely works. Nobody can prove that yet. It's that every fix you'd make is just better writing. If the AI angle turns out overstated, you've still got clearer docs. Hard to lose that bet.

[Simon Moxon @simonmoxon]

Everyone thinks an empty help-centre search means a missing feature. Usually it means the customer calls it something you don't. About one in five is a real gap. Either way it's product research in the customer's own words, and nobody reads the log.

[Simon Moxon @simonmoxon]

You can budget a redesign. You can't budget the screenshots it breaks.

The new UI gets estimated to the hour. The old screenshots in your help centre get nothing. They're wrong the day you ship, and stay wrong until someone notices.

[Simon Moxon @simonmoxon]

"We'll document it later" is a lie you tell yourself at 3pm and forget by 3:15.

Docs debt doesn't arrive in one lump. It builds, one shipped-but-undocumented feature at a time.

If docs aren't in your definition of done, they're in never.

[Simon Moxon @simonmoxon]

Added per-task model choice to my pipeline this week. The hard part wasn't the routing. It was the settings screen: an empty row has to mean "whatever you ran before this existed", not "no model". Ship the default. Don't silently change what's running under someone.

[Simon Moxon @simonmoxon]

Turns out my AI pipeline is not one job. It's six. Four just output JSON. Two write prose a customer reads. Only those two need the expensive model, I'd been paying top rates for all six.

[Simon Moxon @simonmoxon]

OpenAI has the best models on earth and still can't name a product line. Naming, positioning, what to cut: none of it has a right answer. That's exactly where the model has no edge. Taste is the one thing it can't hand you.

[Simon Moxon @simonmoxon]

When your internal tool broke, the person who built it used to be a developer you could hire back. Now agents make everyone a builder, and the thing that walks off with the context is a chat session. No handover notes. Nobody to rehire.

[Simon Moxon @simonmoxon]

"Agents make maintenance cheap, just get a fresh session to re-read the codebase." A fresh session re-derives the code. It can't re-derive why you built it that way. And the why was never in the repo.

[Simon Moxon @simonmoxon]

Building your own tool to dodge a licence fee was always a loan against a future you. Save the fee now, inherit a system nobody can read later. Agents didn't fix that. They cut the interest rate so more people take the loan out.

[Simon Moxon @simonmoxon]

We've built agent-to-agent, sub-agents, specialist agents, all talking to each other all day.

Nobody's built the agent that knows how to sit with a veteran and ask what they never wrote down.

That's the actual gap.

[Simon Moxon @simonmoxon]

Soon an agent will message you asking for help with something only you know how to do.

Your undocumented knowledge is the last thing you own that it can't get without you.

The question was never whether it can ask. It's whether you'll tell it.

[Simon Moxon @simonmoxon]

Ford rehired the veteran engineers it thought AI could replace.

The lesson isn't that AI fell short. It's that the knowledge running any company was never written down, and AI can only read what is.

[Simon Moxon @simonmoxon]

@jasonlk Perhaps AI has enabled people to find the 'Cancel Plan' button in the Adobe portal, so now they're scared.