Technical Documentation Generators: The Good, The Bad & Ugly

Managing documentation comes in a plethora of frameworks. Unfortunately, many technical writers resort to the softer side of their skill sets (i.e. MS Word, MadCap Flare, FrameMaker). Ideally, choosing a tool should be tethered to the intended output type.

When you factor in API resources, the options vary. Honestly, I prefer to discover what the client has built into their UI design rather than impose my preference on their software stack. Some companies have a shoestring system based on outdated processes. It’s the nature of the business representing end-users regardless of clunky workflow.

The Good

Being a card-carrying static documentation loyalist, I believe tools such as Sphinx and Jekyll are the gold standard. OpenAPI/Swagger 2.0 is another solution.

The Slate | Markdown duo is another fabulous option. I had the pleasure of working on a project with Rob Lord. His static site generator is built upon Ruby. View it here on Github. Despite a mild learning curve, it’s fairly straight-forward.

Swagger is a better choice to create a common user-friendly platform between writers and developers. But again, it depends on the client. Don’t forget the tech writing team destined to manage the content must be highly comfortable writing within an editor.

Warning…

The good olds are long gone changing work environments to publish content. Documentation needs to be engineered for streamlined output. Writers shouldn’t be forced to be developers but should be enthusiastic learning how to interact with static site generators.

The Bad

Perhaps not entirely bad, but I have worked on some projects where all of my documentation was written in Confluence. Then dovetailed into JIRA backlog stories. No doubt, it’s an enormous workload and wasted manpower.

Some decision-makers choose to remain working in the stone age. I’ve found the reason is usually poor engineering of fast processing of documentation.

But why?

Skill sets vary depending on the developer team. Especially at the top.

I’ve worked on projects for finance companies which resist new technologies. Likely it’s due to the aged approach to solutions which fit the organization.

Here’s an example…

A thriving credit card processor I’ve worked with still relies on green screen frameworks. Any writer under the age of 40 will likely roll their eyes after reading the previous sentence.

As silly as it may seem, their technology powers millions of transactions per day. Why change it if it works?

My perspective is it depends on the end-users. In their case, most of their users are internal banking clients. So building dynamic help documentation to train users is far more efficient than tearing apart the inner workings of their 30 year old code base.

Another cryptic problem is add-on release updates. In these cases, the product environment is a thriving revenue source considered sacred. Therefore, training users to conform to outdated technology far exceeds the need to retool from ground zero.

The Ugly

Documentation as an add-on. During the design phase, I’ve witnessed major oversight thinking about end-users in regard to UX. Instead, PMs and developers focus more on product requirements (as they should).

The consequences are sloppy quick-fixes to meet release schedules.

Often, the end-user isn’t considered until UAT rolls into the grand plan. Suddenly, the technical writers are handcuffed writing help documentation for a product that wasn’t engineered for simplicity.

Accountability is another issue. Large teams sometimes suffer from professional loafing.

As a contributor, we each serve our role in the SDLC. However, this becomes a global issue for usability. End-users take it on the chin. Thereafter, your support teams bear the brunt of servicing confused customers.