Documentation Migration and Unification

Employer: Adaptavist
Role: Head of Education
Duration: October 2018 to February 2021

In October of 2018, I took ownership of Adaptavist’s product documentation for 25+ apps spread across 6 different sites and domains using 3 different platforms. Customers rated docs poorly and listed them as a key reason for deciding not to purchase or retain our apps, and people would often struggle to find the right doc set or navigate within our docs.

By the time I left Adaptavist in March 2022, we had implemented Scroll Viewport along with a number of other Confluence apps to make our documentation beautiful, responsive, and most importantly, quick and easy to update. Both the technical and the product managers were delighted with the docs, and customers were listing documentation was one of the top 5 reasons they purchased or retained our apps.

I investigated a few different doc solutions such as Sphinx and Antora including building these for proofs-of-concept. In the end, I recommended we migrate everything to a single Confluence site because the cost of alternatives was significantly higher while providing a worse experience for tech writers and our customers.

My role as the lead on this initiative was platform evaluation and recommendation, and that required a lot of stakeholder involvement. I worked with product managers, product marketing managers, and engineers to hear their concerns and ameliorate them. This spanned everything from automatically handling code versioning and display in the docs to permissions and access (around 60 concerns and risks total). I was effectively our tech lead as well for the docs platform and solution, but I negotiated transferring future ownership and maintenance of the new platform so that wouldn’t rest on the technical writers going forward.

I directed Renee Brown, our lead tech writer, to oversee the migration and information architecture improvements for our docs, particularly ScriptRunner which needed a dedicated migration/IA project run in parallel with the rest of the platform and app work.

To anybody approaching a migration which includes apps, the Firespring team recommends diving into documentation early in the process. Some of the add-ons which did not make the cut for their migration were those whose documentation did not offer the necessary insights for simplifying the process. ‘The ScriptRunner documentation is very honest about the difference,’ says Chad. ‘Adaptavist just laid it out. It was refreshing because you don’t always see that.’

Firespring Case Study