Switching from DITA to Confluence and Scroll Versions
Comment
Switching from DITA to Confluence and Scroll Versions
About Time
In 2013, NimbleUser began using Darwin Information Typing Architecture, or DITA, to author the user guide content for our application Nimble AMS. At the time, we were transitioning from using a general word processor to writing with a program specifically developed for technical documentation. We would physically print out the user guide and hand it to our customers. Moving to DITA surely was a huge step forward for us and I want to be sure to point out that many already use this model for their technical writing process successfully. That being said, there were some major issues with DITA that signaled a need for change.
Arduous Authoring
Changes were managed using Git branches for versioning, which added a lot of overhead.
Hard to use and overly complicated editors slowed down even simple content updates.
Most editors were desktop- rather than cloud-based.
Technical writers were spending more time fiddling with the underlying XML than creating content.
Reclusive Review
We had to commit the Git branch, run a build job, and pass reviewers a static HTML site with the content.
Reviewers could only read the new content and were not able to add inline comments, which made giving feedback a disconnected experience.
Each change also had to be reviewed technically to ensure the underlying XML met our standards, making even small changes slow.
Painful Publishing
We had to merge all Git branches together, resulting in merge conflicts and opening new branches for any corrections.
Additional jobs were used to push content to our Help Preview site for customers using the Nimble AMS preview version and then to our Help site for customers using the generally available (GA) version of Nimble AMS.
Wasting Time
Our content creation process was very time consuming and that meant our technical writers had to focus on being “technical” instead of actually writing technical documentation. Perhaps this was not the best way of creating content but few – if any – DITA authoring processes offer a truly cloud-based experience where reviewers can just read, comment, and move on. Every other application we use at NimbleUser is cloud-based; heck, we build a cloud app! To ask everyone in the process to use desktop-based software seemed like a step in the wrong direction.
Though our development process was moving toward continuous delivery, our documentation process was days and sometimes weeks behind.
Time to Switch
In 2015, NimbleUser began rewriting half of our app with the purpose of making it easy to use and customize with a few button-clicks instead of writing code. When I was tapped to write the user guide for this new step in our app development, dubbed Community Hub, I couldn’t help but feel that we needed to take a similar approach to our content creation process as well. We needed writers and reviewers to do their work unhindered by technical tools in an environment that was accessible to anyone via the cloud.
Altruistic Authoring and Responsive Review
I knew Confluence offered that approach and after lots of internal convincing and many struggles, we began using Confluence for the documentation of Community Hub. Writing great content was simple and reviewers could easily add in-line comments to the content. Not only had we caught up in documenting how to use Community Hub within the first few months, but we also began building an include library and reusing content easily. For the first time, we were delivering documentation at the end of each sprint in stride with the development work.
Progressive Publishing
Our authoring and review processes were thriving in Confluence, but we ran into a bit of a snag once Community Hub was released because we needed to publish content for two different audiences. We had to be able to publish two versions of content, one for the GA version of Community Hub and another for the preview version.
We found ourselves trying to author in one space, exporting that space, and importing it into two other preview and GA spaces to help control our versions. This was very tedious and really not the way one should use Confluence. I should probably issue Atlassian a public apology for all the questions we sent their way during this time. It was at this point we came across Scroll Versions and things started improving right away.
By using Scroll Versions, we can now publish a new version of content to our preview space at the end of each development sprint. We can also update the GA version to fix any typos or make small improvements that can be published quickly. Our content (e.g. Nimble AMS Help) is now constantly release-ready, our customers have the most up-to-date documentation possible, and we can publish it with a few clicks instead of code commits.
Time to Move Forward
I couldn’t be more pleased with the move from DITA to Confluence and Scroll Versions. We are now making an effort to move all legacy DITA content into Confluence. That way our entire app will be documented in one place. Now we are able to focus on improving our user guide content, something we lost track of when we were still fighting the tools every step of the way.
It’s great to walk into work on Mondays after a sprint has ended, deliver a new content version to our customers, and start working on a new one. The air is clean, the sun is rising, and I see a true DocOps approach on the horizon.
