The documentation, the least glamorous thing here, and the most read.
- Team
- A researcher and two writers
- Kind
- Rewrite, then a platform
- Audience
- 90+ companies
The manual for a platform people configure themselves, and now a thing software reads too.
Every retailer running NewStore sets it up themselves, so the words are part of the product. It was rewritten from the ground up, moved onto a CMS so 109 people across the company can publish without a developer, and it now answers questions through an AI inside it and hands itself to a model through MCP. 171,400 article views a year.
Nobody gets promoted for fixing the docs.
Which is exactly why they were the way they were: written feature by feature, by whoever shipped the feature, in whatever voice they had that week. Someone configuring the platform had to already know the answer to find it.
Every support ticket that starts “I could not find how to” is a design problem wearing a support team costume. So we treated it as one.
A rewrite, not a tidy up.
- Structure
- A new information architecture, organised by the job rather than the feature. People arrive trying to do something, not to read about a module.
- Voice
- Plain language, active voice, the same word for the same thing. Those rules became the product's rules too.
- Upkeep
- Ownership and a review rhythm shipped alongside the content. A rewrite nobody maintains has a shelf life.
The rewrite was the easy half.
The docs moved onto a CMS, which sounds like a tooling decision and was really an access decision. The old setup needed a developer in the loop to publish, so documentation was written by the few people willing to learn a build pipeline. Now 109 people across engineering, product, support, sales and marketing write and review directly, and they published 378 articles in the last twelve months. Nobody waits for me, and nobody waits for a deploy.
Independent writing only works with a visible quality bar, so the bar is written down and kept where the writing happens: a style guide, a terminology list, the personas, the templates, and a review step before anything goes public. People are trusted with publishing. They are not left to guess what good looks like.
There is an AI answering questions inside the docs now. It took 9,631 questions over the year and answered roughly six out of seven, which means a few hundred people a month got their answer without opening a ticket or waiting for a timezone. And there is an MCP connection, so a model can be handed the documentation as context rather than guessing: 3,498 calls so far, most of them through Claude. The docs became something software reads, not only something people read.
Organised by the job, not the feature.
The left column is the argument.
Set up your mobile POS, engage your customers, use it, manage it. Four jobs in the order a store does them, and a reader who knows what they are trying to do can find it without knowing what we called the feature.
Ask it, and it answers out of the articles.
Every line carries a citation back to the page it came from, which is the part that makes it usable: you can check it. 9,631 questions over the year, answered about six times out of seven.
A third of all reading is one page.
What’s New, the release notes, pulled 58,600 of those 171,400 views. People come to find out what changed far more than they come to learn the platform, which is either a success or a verdict on how discoverable the rest of it is, and I think it is some of both.
One search in twenty still returns nothing: 1,257 of 25,614 searches over the year. That list is not a failure report, it is a backlog. The words people type and do not find are the most honest brief a documentation team will ever get, and the AI’s unanswered questions are the same brief arriving in sentences.
Content design is design.
Most design organisations stop at the interface and hand the words to someone else. I brought content design inside the team and worked through the rewrite with them, because a button label, an error message and a help page are the same material.
It is also the clearest example of how I lead. I did not learn to write documentation so I could do it forever. I learned enough to know what good looked like, hired people better at it than me, a researcher and two writers, and then argued about commas with them until it was right. The team is three. The number of people writing is 109.