Product Docs for CTO.ai

The entirety of the CTO.ai product docs were overhauled and mostly rewritten from the ground up by me. The documentation revamp also involved migrating the documentation from a third-party docs hosting service to a markdown-based Hugo site deployed to GitHub Pages.

My initial project at CTO.ai was a total overhaul of the product documentation. When I began at the company, the docs were in the state I’d expect to find at any company that has had years of development and organic customer growth: They painted a broad picture of the platform and how to use its features, but they didn’t present the cohesive product story necessary for users to build their own working mental model of the product. Given the relatively unique positioning of the product as a DevOps platform oriented toward software delivery process measurement (i.e. DORA metrics), the main challenege I had to deal with was presenting a cohesive product story without creating cognitive overload from the many supporting concepts that also had to be introduced.

The final result is a comprehensive manual that efficiently provides existing users with the goal-oriented information they need to use the product, while presenting prospective customers with the context they need to understand how the product might fit their own team’s needs. The product story I present is built around the idea that reducing friction is only possible if you can identify where the friction exists in your workflow.

Migrating the docset from our previous third-party documentation host was a whole other ordeal… that host loved representing everything in their exports with JSON. Fortunately, those data structurews were at least consistent, so I was able to build some simple tooling to convert the entire docset to a static Hugo site deployed to GitHub Pages.

The full live docset is available at cto.ai/docs, but I have also excerpted only the parts written by me to a single PDF copy. The sections excluded were primarily SDK reference sections that I’ve never had an opportunity to clean up, and which remain in the docs largely as they were initially.

Of course, no massive docs overhaul would be complete without a blog post to announce it! [PDF copy]