Migrating to Docs-as-Code

It was only a short time ago that we migrated to DITA XML. We have been through two vendors and two content management systems (CMS). The second cost less than the first. However, earlier this year, someone in our company advocated that we move to Docs-as-Code to replace the CMS. It would also replace all the disparate systems we were using like Word. The suggestion was vetted and by June we had canceled our contract with the CMS vendor as of the end of this year.

What happened next is somewhat unusual. Two members of our Information Development (ID) team took on the bulk of the work. The entire team curated 1600 deliverables down to just over 1000. Our content was modularized for delivery on a future HTML platform. My colleague has been working on automation scripts to migrate content as well as other things to get us ready to move to Antora.

I love technology. So, I dove headfirst into learning AsciiDoc markdown in IntelliJ. I found that I picked it up fairly quickly.

I already knew how to use Git (command line) from my product work, but now I had to integrate it with the IntelliJ editor and get a repository set up and figure out all the implementation details. Although I wasn’t really clear where I was going, I had a vision and pushed through until I created a single page of installation instructions that include:

  • Prerequisites such as submitting tickets for access to the Bitbucket repository
  • Install IntelliJ
  • Verify access to the repository
  • Install and initialize Git

After the installation instructions were finished, I worked my way through the workflow for creating projects. The following diagram is now part of the overview that is used in the training and documentation for ID, Product, and Engineering teams that will be learning a new way to create documentation.

Along with this diagram is a series of procedures:

The Get started with AsciiDoc is a cheat sheet that I created to introduce people to markdown.

As I worked my way through this, I researched and worked with contacts in development to determine best practices like the following:

  • Require at least one reviewer for a Pull Request. (Due to odd use cases that come up fairly often, we are allowing users to assign themselves as a reviewer.)
  • Feature branches must be named using a Jira and the commit message must include the Jira number.

Of course, we had many other decisions to make such as:

  • Who will be the Bitbucket moderators?
  • How will we notify users that they must perform the installation before attending training?
  • How should users sign up for training?
  • Whom should we train first?

For a while, we were managing these discussions through email and IM. However, as the pressure increased, I started scheduling meetings with my manager and the other ID that was doing a large part of the work.

I did the first training session today. We have 450 users, located across many time zones, to train over the next few weeks.

Currently, I am still trying to determine how to position all this work on my resume. I manage complex projects in support of documentation? That just doesn’t seem to do justice to my role as a researcher, writer, trainer, implementer, planner, and organizer. If anyone has any ideas, I would love to hear them, because I am always considering my next move!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s