Context

In October 2018, I took over Adaptavist's documentation for more than 25 apps spread across 6 different sites using 3 different platforms. The situation wasn't great. Customers rated our docs poorly and frequently cited them as a reason for not buying or keeping our apps. People struggled to find information and navigate between our different doc sets.

This wasn't just a technical problem – it was affecting our business. When customers can't use your product because they can't find or understand the instructions, that's a real issue that touches sales, support, and customer satisfaction.

Challenge

Our documentation problems went deeper than just consolidating websites. Poor documentation had become a deciding factor in whether customers would buy or keep using our apps. This made me realize that documentation, often treated as an afterthought, was actually a core part of our product experience.

We needed to balance several competing needs: creating a better experience for customers, making content management easier for our technical writers, maintaining version control for our engineering team, and building something sustainable. After talking with stakeholders, we identified about 60 different concerns and requirements – from how code would be displayed to who would maintain the platform long-term.

Approach

I started by testing different documentation solutions. I built proof-of-concepts with platforms like Sphinx and Antora to understand what would actually work for our situation. This hands-on testing showed me something important: the fanciest solution wasn't necessarily the best one for us.

In the end, I recommended moving everything to a single Confluence site. While other platforms had impressive features, they would have cost more while making things harder for both our writers and our customers. Sometimes the simpler solution is the right one.

I worked closely with product managers, marketing teams, and engineers to address their concerns and get everyone on board. We implemented Scroll Viewport along with other carefully chosen Confluence apps to create documentation that was attractive, responsive, and – most importantly – easy to update.

I also directed our lead tech writer to handle the migration and information structure improvements, particularly for ScriptRunner, which needed its own dedicated project running alongside our main platform work.

Outcomes

By March 2021, we'd completely turned things around. Documentation, once a reason people avoided our products, had become one of the top five reasons customers chose to buy and keep using our apps. Technical teams and product managers, who were initially skeptical, became enthusiastic supporters of our new approach.

The best validation came from our customers. In a Firespring case study, their team specifically praised our "honest" approach to documentation: "The ScriptRunner documentation is very honest about the difference [of Data Center and Cloud]. Adaptavist just laid it out. It was refreshing because you don't always see that."

Key Takeaways