Before

Challenges

No clear direction for the user

Not 100% on brand outside of the color scheme

An overwhelming amount of documentation lead to confusion for the user (every version had a copy of the same document)

Busy design and a lot of white space

Hard to reuse content outside of Confluence

After

The Solution

Better direction and definition of the products for the customer

On brand design – a collaboration between Marketing, UI developers, and myself

Smaller amounts of documentation (no duplicated documents, they are only updated when needed)

White space is better used and balanced

Confluence was the answer for our documentation pathway when originally implemented in 2014, but after a year of release cycles, it was becoming obvious that it was not sustainable. We had 50 spaces related to publishing (although not all public) and the number continued to grow with each release. Even with help from Atlassian, we couldn’t come up with a feasible solution, so I began researching other options.

Phase 1 – Set requirements and research

I, along with the group of Technical Writer III’s evaluated several options – CMS type solutions (which we determined we would have the same issues with eventually) like Docusaurus and Palagio, blog-like solutions like Jekyll, and docs-as-code solutions like Hugo using a git repository. After evaluating the options in test environments, we determined moving to a docs-as-code workflow made the most sense and decided on Hugo.

Phase 2 – Plan the design and migration

The Design

Templates had to be built for Hugo, along with a new theme, so the UI Developers, UI Designers, Dev Managers, and myself met to determine what documentation would look like in Hugo. With the company and product branding guides in mind, we created multiple assets that help to shape what the documentation is today. Assets (icons, logos), Templates (Installation Guide, Articles, Knowledge Base, How-to, Taxonomy), and Content Templates (allows for summary views) were the product of this collaboration.

The Migration

There was no easy way to do this. After evaluating the current documentation, it was determined that there were close to 700 documents that would need to be moved. Exports from Confluence in HTML produced a lot of cruft that would have to be removed, making the process even longer. It was determined that a copy of only the content would be used and each file would be created individually. Each landing page and subsequent page had its own Jira case in our Transition project.