Documentation platform rebuild for a payments API

The company sold an API to other developers, and the documentation was the product's front door in a very literal sense — the sales team's demos ended with a link to it. It was in three places: a generated reference that was accurate and unreadable, a set of guides in a wiki that had last been updated across two major versions, and a pile of examples in a repository that no longer compiled. Support could see the cost directly, because a large share of tickets were questions the docs technically answered somewhere. Integration time for a new customer was the number the business cared about, and it had been getting worse.

Technical writer and the effective owner of the documentation platform, about ten months, working with two engineers who gave me a day a week each, a developer advocate, and a product manager who sponsored the work. I did the writing, the information architecture and most of the site build; the engineers did the parts of the generation pipeline that touched their code. I also ran a fortnightly session with two support agents going through the week's tickets, which set the priority order for what I wrote.

I owned the structure — deciding what is a guide, what is a reference, what is a tutorial, and refusing to let those blur, which is most of the work in a docs rebuild. I rewrote every guide, about sixty pages, and I owned the example programs: they live in the repository, they are compiled and run against a sandbox on every build, and a failing example fails the build. That was the change with the most argument attached to it and it is why the examples are still correct two years later. I also built the site itself and the search, and the redirect map from the old wiki, which mattered because a lot of the wiki pages ranked well.

The decision I had to fight for was making examples executable and part of the build. Engineers reasonably objected that it would break their pipeline for a documentation problem, which is exactly the property I wanted — an example that does not compile is a defect, and until it fails somebody's build it stays broken. We compromised on a separate required check rather than a blocking one in the same pipeline, which was enough. I also decided to write the reference by hand for the twenty most-used endpoints and leave the remaining generated, against the tidier instinct to generate everything: the generated output is complete and tells you nothing about when to use a field.

The API kept shipping while I was rewriting, so I versioned the documentation from the start rather than retrofitting it later, which cost about three weeks up front and saved considerably more. Anything describing money movement had to be reviewed by the compliance team, and their turnaround was a week, so I batched those pages and wrote around them. I had a day a week of engineering time and no more, so I designed the pipeline to need almost none of it once running. And I could not take the old wiki down until search traffic had moved, which took about four months of running both.

Median time from a customer signing to a first successful live transaction fell from around eleven days to six over the two quarters after launch, which is the number the product manager put in front of the board and which I would caution is not all mine. Documentation-shaped support tickets fell by a bit over forty per cent. The examples have failed the build eleven times since, each of which is a case where the docs would previously have silently lied. The thing I am most pleased with is smaller: the developer advocate stopped keeping his own private set of corrected examples, because he no longer needed to.

The developer advocate knew exactly where people got stuck and gave me the ordering for the first three months of work. The two engineers built the example test harness and were right to insist it not block their main pipeline. Two support agents sat with me fortnightly for the whole project, which is the single practice I would repeat on any documentation work.