Select Page

Authoring Tools

Ask most technical writers about UI integration for help documentation and they’ll like reply, “Huh?” The evolution of web-based help content has been a struggle for many corporations of all sizes.

Which solution is best? It depends. Mostly on the expertise of your writers and how they communicate with your development team.

Cutting Through The Chaos Clutter

Project managers and scrum masters rely on programmers to advise them what types of UI solutions are best for your software product documentation needs. However, the challenges are diverse. Primarily due to:

  • A disconnect between developers and technical writers
  • Too much reliance on simple solutions versus smart user experiences
  • Temptation to integrate retail software products into your UI platform

The chaos and clutter is often in your team’s ability to engineer dynamic UI/UX solutions which take user needs as the top priority.

Pesky Proliferating Pages

Have you noticed it? At some point help documentation creators and developers took a secret solemn oath to clunky reams of help pages. Crazy at it may seem, building deeply nested page architecture relying on link navigation is the standard style for millions of help systems.

What’s the big deal right? Wrong. Users aren’t trolling through your documentation on their coffee breaks like they consume sports, entertainment and news sites. They want relevant answers in seconds. So why are you forcing them to navigate your help content the same kludgy way?

Believe me, I’m not a fanatic. But I’ve seen enough awful designs to assure you this trend is unacceptable to your customers. How many clicks or searches does it take your users to find accurate information? Hopefully no more than 1 or 2.

Is there a better way to get yourself off the crack cocaine of page addiction? Yes. How many pages can you get away with documenting all of your help system…

  • 10?
  • 15?
  • 20?
  • 50?

Try one. Actually, that’s a lie. I recommend a minimum of two unless you don’t offer API documentation and code samples. Then definitely one. Unless your help content requires large screenshots and graphics outlining lengthy instructional steps. In these cases, you may want to consider building page templates to match the styling of your index page. Then link out to a few broad topic pages covering sets of functions.

I know, lots to consider. But the benefits of adopting a static UI/UX are far too user-friendly to ignore.

Ideally, you don’t want your vanilla users to have to sort through API code samples. So I do recommend API as a linked out second page. Keep reading to discover why.

Help System Case Study

In 2014, I was contacted by a multi-national conglomerate with a big problem. Their sprint teams were pushing the use of MadCap Flare as their CMS. However, integration was the blocker.

Their server stack was Linux. So integrating MadCap wasn’t an easy option since it requires the Microsoft .NET Framework 4.5.1. Unfortunately, hosting their MadCap instance on an AWS .NET server wasn’t conducive with their technology management’s devotion to hosting all applications locally among their server stack.

This type of challenge is common. Remember, there needs to be a unified exploration between DevOps management, developers and product managers. What about the technical writers? Unfortunately, too few of them have programming skills to guide projects through the entanglements of content production and publishing within an application’s architecture.

Alternatives to MadCap Flare

During a conference call the usual suspects chimed in..

Despite these suggestions, their integration and long-term scalability are limited. True, flat file architecture is an obvious solution. Many of the powerhouse finance providers (i.e. Stripe, Paypal) use them. But the lurking issue was choosing a solution which bridged the gap between integration and access for writers.

Adding even more fuel to the fire was the product manager’s insistence to make a decision quickly since their first release would be launched within six months. So choosing a robust API documentation publishing tool was critical to get into future sprint backlog stories.

My Recommendation: No CMS

Due to the weight and lag time relying on heavy database CMS solutions, I urged them to ignore the temptation to consider all-in-one CMS providers.

The problem is once you pull the trigger, you’re entire future development hinges on the CMS backend. Ouch. What often appear like good decisions usually end up becoming expensive blockers when future upgrade designs evolve.

Furthermore, I suggested they reverse-engineer their API documentation focusing on what end-user programmers need to get connected quickly rather than what was easiest to supply them.

The cringe factor of writing clunky API PDF documents was clearly not an option.

Unfortunately, I’ve spoken with too many product teams addicted to 20+ year old workflows. No one, and I do mean no one, finds dated PDF file help documentation useful.

Authoring Tool Madness

Beware. What I’m about to tell you won’t go over well with many of your team members. Too many developers and scrum teams along with technical writers subscribe to the concept of professional loafing. Having worked with many teams, I see it all of the time across many verticals.

Programmers build product. Technical writers write. What’s missing? Accountability to engineer scalable, industrial-strength help documentation. “Good enough, that works for me or it’s not my job,” are a few of the perspectives. Not always, but often quick, easy, one-size-fits-all approaches to authoring tool solutions are the standard thinking.

Keep in mind, your developer team shouldn’t quite bear the brunt of this challenge. Nor should your technical writing team. Who then? Your project managers. They need to be thinking years down the road when considering scale and integration rather than crushing two week sprints.

Choosing the granddaddy authoring tool for your application needs to be carefully considered as paramount to exceptional user experience. Nothing else matters. Avoiding this mission-critical decision will result in a backlash of tickets, frustrated service reps and salespeople going bonkers dealing with confused customers.

The Solution – Stripe-ish

I’ve worked on many projects in the last two decades. One was consulting with a development team working at Stripe. Rather than divulge sensitive backstory, I will confess they have cornered the market in API documentation content. Specifically with their three column design. Programmers absolutely love their simplistic yet dynamic format:

api technical writer


Unfortunately, not all scrum teams have the manpower bandwidth to build HTML/ERB templates and export them with a Sinatra-like DSL. But there’s an alternative which is far-less complex for your developers and technical writers yet provides a Stripe-ish UI/UX. It’s a hybrid mix of Slate and Markdown.

Don’t be fooled into thinking the above Stripe graphic limits you to just API help documentation. I’ve built full help systems using this three column format. The benefits are far too phenomenal to ignore such as:

  1. Lightweight, flat, static .md file structure.
  2. Speedy fast one page functionality (no database).
  3. CSS customization is a breeze.
  4. Clean, intuitive layout for easy access of relevant content.
  5. API multiple programming language examples (third column).
  6. Host on GitHub if you’re in need of user feedback.
  7. Or host on your on servers exporting Ruby code to .md files for publishing

Beware of Usability Issues

When are static help pages a poor idea for an organization? It’s something I consider when working on new contracts. Remember, if your internal technical writers don’t have basic HTML skills, you’re grand plans are sunk. There’s two schools of thought…

First, if you’re thrilled by using a static page structure, you’ll need to your scrum masters to write backlog users stories for your help content. Although hardly rocket science, it will tether your writers to sprints. But that’s actually a good thing. The more you can draw writers into the SDLC the more dynamic they’ll become as contributors.

Plus, when their first round of drafts are complete, use them for product testing. Technical writing is a craft which requires fanatical attention to detail. I’ve seen writers perform far better at UAT than members of the product team.

Second, static file platforms are an awful choice if your writers and managing editors require access to a CMS UI.

Another issue to consider is when you have limited developer manpower. Count on one full-time programmer to build the UI templates. I’ve done both the design and writing myself. However, I’ve been programming for many years while also writing for a living for a few decades. So diving into deeply nested code to update text content is a walk in the park. For most technical writers there’s no chance.

When Static Help Pages Are Flat-Out Wrong

Another scenario where database CMS structures are better than static are in large product-based organizations. A perfect example are ones such as Amazon who rely heavily on product databases. Cleary these types of verticals require monster database help systems.

Something too few companies consider is off-site resources. Having worked in the finance industry for a long time, I appreciate the concern for security. But don’t forget, AWS has been fully PCI compliant since 2005. Rather than own the server stack, rent it is my approach when suitable for corporate structures. Especially when you have the combination of high bandwidth needs to serve customers accessing heavy media files.

Regardless which authoring and publishing tools catch your attention, be very cautious. Scalability is mission-critical.