To be honest, this is a post I’ve wanted to write for years. However, because of my commitment to clients and projects, I’ve restrained myself from spouting off about the 800 lb. gorilla.

This sneaky monster-like breakdown is breeding throughout many software development projects. From San Francisco to Atlanta, I’ve seen it lurking in Fortune 100 companies to dominant financial institutions. It’s the disconnect between technical writers and programmers.

Communication Chaos

Writers interview SMEs. Then elaborate technical information into digestible content for end-users. Developers dive deep into code sets, cloud-based resources and make commits of their code to version control. What brings them together other than JIRA?

Very little.

The evolution of software products and apps have grown exponentially in the last five years. The runaway freight train consequence is lackluster user documentation. Gone are the days when help guides were churned out, edited and printed to PDF. I can’t say I miss the madness.

The disconnect between technical writers and programmers is the new challenge. Suffering through product development and elaboration is now considered the holy grail of a successful product releases. Unfortunately, much of the blame points to us writers for lack of technology skills.

Context Clarity

Face it. These days very few users have the time to…

  • Struggle through long-form help guides
  • Determine the best phrase to search for help
  • Waste time trying to learn your product because of poor UI design
  • Submit a ticket and wait for a response
  • Remain on hold hoping to speak with a knowledgeable support person

The alternative is far better: developing an intuitive user interface which aids users how to interact rather than wonder.

The result of a user-centric UI design is far less documentation needs. Less is actually more. But it takes time and a prudent approach to pinpoint your user expectations to streamline their access and acceptance of your product.

How do you implement such a beautiful UI?

Get your technical writers deeply involved with product testing. They are by far the best people to dissect problems and identify information brick walls. Instead of them writing 592 page user guides, delegate their manpower to helping programmers simplify the user experience.

End-Users Instead of Requirements

Back in 2015, I consulted a finance company to help bridge the gap between developers and writers. They were struggling to overcome too much reliance on product requirements. You know, thousands of backlog stories starting with, “As a user I want to…”

Their problem was engineering solutions without truly understanding the knowledge gaps of users. These were customers that needed simplified access to credit card transactions within the UI. Many of them were also banks which accessed my client’s systems through an API configuration.

We eventually developed UI solutions to overcome lengthy help support. Not always, but usually there’s opportunity to cut through the confusion by building intuitive interfaces rather than clunky portals.

To support end-user programmers tapping into the API, we built a one-page dynamic documentation module. Read more why we abandoned lengthy portrait-based frameworks.

Why Users Come First

Successful companies overcome this challenge of requirement elaboration by investing in UX as a priority beyond merely churning out help documentation. Remember, your users are the litmus test of elegant usability. If they suffer, your product is void of marketability.

My experience since 2001 has gone from writing long-form technical documentation management to UX methodology enhancement. Time is a commodity few users are willing to give up to fumble through your help system. If you haven’t accounted for predictive user brick walls, your support tickets will escalate.

An intuitive UX is must and is now the industry standard among power providers such as, and

The fall out is how writers are engaged in the SDLC. Especially in their contributions to user experience. Traditionally, product requirements have taken priority over building dynamic user interfaces which lead users where they need to navigate.

To defend users, I like to reverse-engineer their expectations. It’s not common in the design process for obvious reasons. For example, an online financial payment tool relies on a plethora of permissions, validations and functional connections to payment processors. In these cases, you’re limited by design requirements.

However, UX should be hardwired into the flow and navigation plans. Far too often, developers code solutions which are difficult to understand from a procedural flow.

The Solution?

Simplification of user documentation within the UI should be the first task. Never has a user wanted to pilfer and search through reams of technical jargon to pinpoint the answer to their problem.

Next, comes robust search functionality with conditional tagging. It’s hardly a topic considered in the design stage. Yet, smart companies integrate relevancy formulas and modify them based on user search query trends of the help documentation.

Remember, if you can’t serve up the most relevant answers to your users in seconds, you’re doomed.

Lastly, analytics should be tethered to your UI. Navigation challenges, abandoned sessions and every conceivable user metric should be evaluated 24/7. Big data is the secret sauce to refining your product once users are knee-deep in your system.