Building a New Publishing Process While Developing Content for a Future Product Release

We recently completed the first phase in a significant new project. It required designing, building and implementing a new documentation process, while at the same time developing content for three new products.

Our client builds mobile application software development tools. They were looking for a tech writing company that also could make their documentation process more agile and productive.

The process they were using relied on structured FrameMaker which then was converted to HTML and PDF files. But they found this slow, hard to manage, and outdated. Our role was to design a new content development and workflow process and to assist in its implementation.

At the same time our tech writers would be working with their software developers, who are located at different regional centers. We would have to develop a working relationship with remote experts and collect, develop, update, and publish content in a timely manner.

The group assigned to the document publishing process set about exploring different publishing processes. The group assigned to developing content immediately started working with the subject matter experts.

The Publishing Process

To start, we examined several options for publishing content to the web. These included Python, Sphinx, DocBook, Slate, and others. We built demo sites to show their look and feel. And we evaluated their ease of use,  their output templates, their suitability for the client’s resources and processes, and their scalability.

As a software development company, the client was already using Atlassian’s enterprise software tools for issue tracking and team collaboration. The Developers, our subject matter experts, were comfortable working within Confluence, the Atlassian wiki, to document the products. And Confluence uses a REST API, so the wiki could be queried and content pulled from it.

We realized that if we could continue using that wiki, the Developers would be much more responsive in delivering the content we needed. We also could use JIRA, the Atlassian issue tracking tool, to monitor issues blocking content development.

The goal then became to build a process that used the wiki and integrated seamlessly into their workflow. The result would allow the client to be in complete control of the process, without having to learn any new technologies or tools.

However, important issues remained to be solved.

Because they had in-house NodeJS resources, we proposed using DocPad as the interface to pull the content from the wiki. To get this to work, we built a special DocPad plug-in to automate the query and pull the content from the wiki. The content was rendered to templates built for customer-facing content and then deployed to their AWS servers.

The following screenshots show the content as developed in the Confluence wiki and the output as it appears on the company’s web site. Changes made on the wiki can be scheduled to appear on the web site whenever you want.

Confluence wiki page	Public-facing content

So what does this mean for you? First, we listened to what the client wanted. We worked with them to determine the best approach to the problem, and we made maximum use of their in-house resources. The result was a process that they completely control. At any time, anyone in the company can view the current status of the content …. There’s no hiding, so you’ll always know if the content will be ready with the product at release time. And when it’s ready for release, it can be pushed to the web site and packaged with the product build as part of the SDK. Fast …. Easy!

By the way, if you’re interested in the DocPad plug-in, you can get it at NPM (Node Package Manager):

https://www.npmjs.com/package/docpad-plugin-conflux

GitHub:

https://github.com/phoenixtechpubs/docpad-plugin-conflux

Developing Document Content

Of course, what good is a process if you don’t have content to publish? The first issue the tech writers had to resolve was developing a working relationship with subject matter experts located in three geographical regions. Site visits could be made to the local office, but video conferencing tools were needed for remote sites. Two that we found useful were Google+ Hangouts and join.me by LogMeIn, Inc.

Working with the subject matter experts, the tech writer created wiki pages for the product content. Links to those pages then were sent to the subject matter experts so that they could write, review, and correct content. The “Watch” feature in Confluence alerted participants to any changes; the “Talk” plug-in was used for contextual Q&A exchanges. The tech writers ensured that the content was written with a consistent editorial style, that it fit within the overall organization of the material, and that there was a smooth narrative throughout.

During the development process, the wiki content was published to an internal review site so that anyone with authorization could see what it would look like when published to the web site. This was important because the template for the public-facing content is branded differently from that displayed in the wiki.

Document control was handled using Comala, the Atlassian workflow product. This ensured that the content went through the company approval process before being released to the web site.

So how did this work out for the client? They were never in doubt as to the availability of the documentation when it came to product release. And those last minute changes that came in were no problem at all.