The Butterfly Effect – Transforming Legacy Documentation

Polina Zaichkina is a Senior Technical Writer at Codat. She produces and edits public documentation, monitors the OAS, and enables others to contribute. In this article, she discusses transforming legacy documentation.

The decision to completely replace an existing documentation solution is usually big, with strong reasons underpinning it. It brings a whole set of other challenges, even unexpected ones. It combines changes to your tooling, team, process, and content.

At Codat, we used ReadMe as our CMS. But as a company, as our needs grew and strategy changed, it no longer suited our needs. In short, we outgrew ReadMe. We were facing several challenges with the status quo of our documentation, and we wanted to resolve them with a migration. We, first of all, had loads of information that we wanted to capture, and there was a specific way in which we wanted to organize it, and the out-of-the-box solution that we had did not support the information architecture that we desired. We also wanted to add richer content to our documents, but it wasn’t easy to put into the CMS. For example, for something as crucial as diagrams, we have to embed images of the diagrams rather than building out the diagrams themselves in the raw text to make them available for editing later. We also wanted to collaborate more with our colleagues outside of technical writing. But we didn’t have a straightforward, repeatable process for creating drafts, reviewing, and approving them. The number of admin seats available to us also limited us. It meant all of the content in the company had to be produced by technical writers, and they worked full-time on creating content just to manage the volume of requests for changes and new content. We felt that working with a bad baseline and trying to improve it was pointless because we could never achieve what we wanted to achieve. There wasn’t much to improve, and we felt we had nowhere to grow.

Using our engineering talent, we built a solution. We spent several weeks migrating the content and upskilling ourselves with the new tools. After that, we started to enjoy the benefits of the move. We now have a lot more flexibility in what we can build and style. This means that visually, our documentation aligns with our product and marketing product portals a lot more. We can also embed a lot more than we used to. We now have around 30 people who regularly submit content for our docs. It required minimal upskilling and buy-in. The entirety of Codat is behind our documentation, and we are tapping into the granule of knowledge across the organization in real time. Since all the changes follow the Git workflow, our contributors are extra confident. They know that their changes are always reviewed by a technical writer first. We also appreciate the built previews that we could get by using SSL, where we can see what we will get as a result of the change. This led to a much better quality of updates, a better understanding of how docs architecture is organized, and increased confidence in contributing from the technical writers and our colleagues outside of the tech content team. As a result, we are now a much smaller, more responsible, more responsive team with a faster turnaround and a much wider range of skills.

Lessons Learnt

• First of all, be clear on your why. You have to understand exactly what the issues are with your current documentation, what problems you’re trying to solve, and whether migration can truly solve these. Understand whether you legitimately need migration and what kind of changes you hope to achieve. As a result, you need to know where you’re transforming from.
• You must know why you are doing it. This can be anything from cost considerations to business and product changes to a desire to simplify or align an existing documentation process. Once clear on that, you must communicate these challenges to others. You have to share the challenges and the concerns that you have with your stakeholders, you have to explain the value of the move. Perhaps it’s not going to be just from a documentation perspective, it could be other contributing factors as well. For example, one of the reasons we looked at changing the architecture was because the company changed its business strategy, and we needed updated documentation to support the new product suite.
• Just take the plunge. If you identified the need for transformation, it’s unlikely to go away on its own; your existing solution will continue lagging behind your needs, and it will become a much harder, longer process if you were to revisit it later.
• Leverage your skills in your team or the wider company if you have that support. Technical writers have a multitude of talents and are usually quite keen to learn. Spend time with your tech writing colleagues to discuss the experiences they’ve had and professional interests that they might be hiding because you never know what new opportunities they will open for you and your documentation.
• Do your research and try multiple tools. Many options on the market require minimal technical knowledge and provide templates for you to start with.
• Prepare to be annoyed. Moving from one tool to another might not be a very seamless experience, especially if you’re moving from a What You See Is What You Get editor to something that works with raw markdown, as we did. Save yourself some anguish and look in advance at the tools that could help you migrate.
• Do ask others for help. In the first couple of weeks of migration, we relied quite a bit on our colleagues across product and engineering to manage the volume of changes that needed to happen.
• Documentation should be a shared responsibility because it does not exist on its own. It’s part of the product that your company sells, so you must share it with your product peers as well.
• Collaborate with and enable all people whom you look for help and with whom you would like to share the documentation responsibility. Provide content and architectural guidance to them so that they know what standards you have, what style guide you’re using for documentation, and what tone of voice people are meant to be using, just so they’re clear. They can give you the best input and be the best collaborators that they can be.
• Migration would involve a full audit of your docs. Identify potential opportunities for improvement. Record feedback or ideas that you get.
• Iterate and experiment on what it’s going to look like. Check the new navigation, the new set of pages, and how the information is going to flow from one place to another, actually building it out and seeing what it looks like physically in the new tool. This may bring forth additional opportunities for improvement.
• Arrange and communicate a documentation freeze. To launch a new documentation solution, you must pause the old solution at some point and start with a new one. Be ready for double maintenance, as for some time; you may need to update both versions of documents on the old and new tools.
• Avoid changes that might become irrelevant. Things like styling, typos, icons, graphics, etc can be done later. Ensure the public documentation is accurate as per product functionality.
• As the documentation changes and processes change, the team also changes. New tooling also means you’d need to develop new skills, so expect and embrace upskilling.

The whole migration process also helped highlight the importance of documentation, first of all, by demonstrating the effort that was put in to make that happen. Once we asked people and others to start getting more involved, contributing, and collaborating on the corrections we’re looking for, people truly appreciated the volume of content we have and the sort of quality of content that we produce. Our new docs have received plenty of compliments from our clients, which is also a great way to demonstrate the value of the migration that we did.