Incognito Hosted Help

The Incognito documentation team wanted to migrate their documentation online. At the time, they would generate PDF documents that would accompany the software packages. This format was not easy for customers in the field, nor did they want to print manuals with each release.

Discovery

To kick-off the project, I first met with the documentation team to better understand their process. The procedures, tools and challenges.

Flow for documentation process
Mapped flow for documentation alongside product development

After mapping their workflow, it was evident that they were satisfied with the tools for content development as well as using DITA method — a technical writing methodology that is XML based with presentation decoupled.

The next step was to design a process. Though the tools can output HTML-ready files, the organization has multiple products, components and versions that added complexity to the document library.

I conducted a brainstorming session with the team to work out the structure and relationships articles have with products. Together, we mapped out a schema to get a build the relational database upon.

Initial schema for the article object for hosted help

I wanted minimize workflow disruption and automate deployment. So I proposed to utilize metadata to store crucial product, component and versioning information.

Prototype

For the first prototype, I wrote a script that took HTML documents, parse the relevant metadata and store them in a database.

I worked on the script incrementally, sorting out initial output issues and edge-cases. I also started work on presenting the documentation on a website.

The prototype processed documents to store in a database

I kept the layout simple and used a breadcrumb navigation style to traverse the website, using the schema defined earlier as a guideline.

MVP

With a prototype in hand, it was time to test. I piloted a product that had an upcoming version release, then offered the usual PDF documentation along with the online version. Initial feedback from customers was positive, and the leadership team gave the green-light to expand.

Refining the help documentation platform for MVP

Outcome

Because I prioritized automating as much as possible, there was minimal workflow changes required for the documentation team. This allowed the team to transition quickly as they could continue to use the same production tools.

Updated flow for online documentation process
Overtime, the process decouples documentation from packaging, allowing help docs to be maintained independently

By leveraging scripts to do the heavy lifting, other benefits were realized, such in-application linking — no more telling customers to go to page 73. In less than a year, all products were added to the site.

Automating workflow allowed us to expand across the product family quickly