Tackling Quality & Bottlenecks in Technical Writing

This article explores strategies in achieving quality and avoiding bottlenecks in technical writing. It is a shortened adaptation of an April, 2021 interview conducted by technical writer Kasia Pranke of Antwerp, Belgium, as part of her Makes Sense series, which aims to cover topics related to language and technology. The original audio recording is available on YouTube.

How did you get started in your career in technical communication?

Before I began my writing career, I worked in publishing as a statistical illustrator. I created charts and graphs for publication in periodicals, business reports, and financial magazines. I also worked in the newspaper industry as a layout artist and eventually production manager for a business newspaper in the early days of digital publishing. I also worked briefly as a medical illustrator.

I was contacted by one of the biggest US computer book publishers to write a technical retail software guide on a certain computer graphics application. That kicked off my career as a tech writer.

I started my writing career as a technical journalist in the aviation industry. I leveraged my experience as a pilot and got a job writing and illustrating technical articles about aircraft systems and maintenance, and airline operations. I interviewed aircraft maintenance personnel and produced technical articles for the company’s maintenance newsletter. It was a fun job and I traveled to many places. But, it paid very poorly. I was able to perfect my writing and illustrating skills and became a subject matter expert with graphics and publishing software.

Following a layoff, I began doing freelance and contract work for the print media industry. I freelanced as a photographer, graphic designer, and illustrator and wrote articles for design, graphics, and computer industry trade journals. After a short time freelancing, I was contacted by one of the biggest US computer book publishers to write a technical retail software guide on a certain computer graphics application. That kicked off my career as a tech writer. It was gratifying to see my work available in bookstores.

What were your next steps?

From there, I continued writing articles on design and illustration software for trade publications and design magazines between authoring more books. I eventually authored several dozen retail technical guides for various large, US publishers, like Macmillan Computer Publishing, QUE, Osborne/McGraw-Hill, Peachpit, and others. Some books I authored as the sole writer. Other books I produced by assembling temporary writing teams. I also assisted other authors and publishers in providing illustrations, technical editing, and peer reviews for specific book projects.

After that, I leveraged this experience in working contract roles in technical communication and technical marketing for a variety of IT companies closer to home. I accepted a part time position teaching business communications, technical communications, project management, and computer graphics courses at a local Canadian technical institute.

I’ve worked as a technical writer, technical Illustrator, technical editor, and team manager both as a full time employee and on a contract basis. My recent employment roles were in management positions with leading IT companies, including Polycom, Teradici, and CA Technologies. I managed local and diverse technical communication teams including managers and contractors. Plus, I worked as a consultant and business owner.

As a Technical Communication Management Consultant, what type of assignments are you working on?

I’m currently doing contract work mostly for technology companies in need of help managing content teams who produce things like technical product documentation, knowledgebase content, technical marketing content and instructional courseware.

As a consultant, I provide companies with guidance on improving team productivity, content quality, team building, strategy, as well as process and workflow.

I work with clients developing both hardware and software products including telecom, utilities, transportation, media, healthcare, VOIP, PCoIP, RFID, ecommerce, and aviation. As a consultant, I provide companies with guidance on improving team productivity, content quality, team building, strategy, as well as process and workflow. It’s very different from being a full time employee and the work product is extremely varied.

What is your definition of quality in documentation?

For me, quality documentation is written using plain language and features all of the four Cs – Clarity, Comprehension, Conciseness, and Credibility. When I see product documentation that enhances the customer experience and that adds actual value and is sought after by people using a product or service, then I know it’s been well-composed.

Companies often view documentation as a way of reducing support costs. The trap they fall into is thinking the cost of producing the documentation must also be as low as possible.

Unfortunately, for many companies, the quality recipe can be very elusive. More often than not, it's because technical writer are focused on pleasing the wrong stakeholder. They focus exclusively on impressing engineers instead of the product customers or end users. There’s an old saying – write to express, not to impress. To me, that means the content must be written to be plainly understood, clear, answer all questions, and be free of complex jargon like acronyms or undefined, industry specific terms.

Another big quality factor is that companies often view documentation as a way of reducing support costs. The trap they fall into is thinking the cost of producing the documentation must also be as low as possible. Companies will offshore their writing teams to low-cost countries, underpay and overwork writers, and drastically reduce content. Writers are told to keep things brief, omit diagrams and illustrations, or eliminate screen shots. While this certainly cuts costs, it negatively impacts quality and defeats the purpose of having comprehensive documentation. It's also the opposite of what the customer wants and needs.

There’s an old saying Cost, Quality, Speed – pick any two. In fact, that holds true for many things. Quality usually costs a bit more, requires more care and attention to detail, requires professional experience, and takes a little more time or planning. But it’s always an investment that pays valuable dividends.

I’ve seen documentation teams fall into so many different kinds of traps in their goal to cut costs. They make poor choices using poor judgements based on lack of experience, misplaced priorities, or poor leadership.

I’ve seen documentation teams fall into so many different kinds of traps in their goal to cut costs. They make poor choices using poor judgements based on lack of experience, misplaced priorities, or poor leadership. It can ruin the product experience, reflect poorly on the product, or even threaten human life (just ask Boeing). Once you fall into those traps, it’s difficult to climb back up. The company loses credibility and the documentation team members get blamed for the issues. That’s where I come in – to identify the issues and make recommendations to get the team back on track.

Who should be involved in the documentation process? What are the common pitfalls, and who is often missing?

Good documentation involves skilled writers and a good plan that all stakeholders agree on. The process needs to include product managers, product owners, developers, support, training, and possibly marketing.

The first pitfall I see often is poor leadership where technical writers are managed under the wrong work group or for the wrong manager. Getting that wrong can be devastating for both the company and the technical writers.

There are lots of common pitfalls that result in poor quality, incomplete, or incomprehensible product documentation. But, I would say there are two big issues. The first pitfall I see often is poor leadership where technical writers are managed under the wrong work group or for the wrong manager. Getting that wrong can be devastating for both the company and the technical writers. I’ve seen technical writers reporting to sales or marketing which frankly doesn’t work in most cases. I’ve seen people promoted to team lead or manager as a thank-you for doing good work, or as a retention strategy. That almost never works out well. Good people and project management skills are learned, not appointed.

Honestly, the ingredient missing most often from the equation is good, experienced writers.

The next most common pitfall is technical writers working in isolation where they are cut off from the areas they need to be closely connected to, like product management, development, support, and customer feedback. Ironically, that leads to writers omitting context, understanding what the customers are trying to accomplish, or where they are having issues.

Honestly, the ingredient missing most often from the equation is good, experienced writers. Frankly, that’s almost always caused by the wrong people hiring the technical writers. They often have no idea how to build a good team, how to manage team development, choose the right tools, or establish workable processes or workflows.

What is the makeup of a good documentation team?

The best teams are usually those who are led by experienced leaders who have deep roots as very good writers, are highly organized, and have excellent project management skills. Good managers understand that their own success relies on building and developing strong team members. They know how to eliminate obstacles, juggle resources, balance priorities, and create smooth workflows. And, they have empathy for their team, the stakeholders, and the customer.

The best teams include both senior and junior technical communication professionals who can write, edit, illustrate and who also understand content management, single-sourcing, web and digital publishing, and project management.

The ideal team features a mix of fixed seniority levels with diverse skills. At a minimum, the best teams include both senior and junior technical communication professionals who can write, edit, illustrate and who also understand content management, single-sourcing, web and digital publishing, and project management. A team with a diverse skill set can add incredible value to the company.

What are the common bottlenecks in the documentation processes and how to deal with them?

There are certainly all kinds of things that can negatively impact the process. I’ll mention four that I think have the most significance.

Planning for timely and accurate communication

Tech writers are often developing product information during product development. Some information is even developed during product conception, beta, or, prototyping. If the goal is to have both the product and the documentation ready for release at the same time, then the tech writers need to have information about features and functions during development. That means product managers, product owners, and subject matter experts need to plan for the time needed to communicate with writers. Without this clear expectation, people are going to say they don’t have time, or it’s not their job. That’s an attitude that will eventually make the documentation into a bottleneck. Documentation is part of the product, so documentation time needs to be factored into any production cycle and the expectations need to be clear.

Overly bureaucratic or silo-type organizations

Blocking tech writers from the people/systems they need to access is another common bottleneck. The technical writers need to learn the product, understand the experience that using the product involves, and accurately describe the features and functions for the customer, end user, or specific audience. If access isn’t provided or available, the team manager may need to resolve it.

Slow or undefined approval processes

Not delegating responsibility to reviewers and approvers. Nailing this is a must, because this is often where time can stand still. Technical writers should not waste time chasing reviewers and approvers. I’ve created approval workflows that put the onus on product managers, product owners, and reviewers to provide their approval by a specific date, allowing for requests for corrections and revisions and tentative approvals. If the company uses a sharing platform like Confluence or Sharepoint, this is easily organized. That way, approvers can collaborate or debate so long as they approve on time. The tools end up doing all the work and everything is tracked by the tool.

Inadequate tools or templates

Not using the right authoring tools, templates, publishing formats, content management, or archiving tools will always cause issues and bottlenecks. Ideally, after authoring and producing the content, everything tech writers need to do should be automated as much as possible. That includes following well-defined templates, reviewing and approving the final drafts, translation or localization, generating final output like HTML or PDF, archiving, and preparing for future iterations.

One thing I often encounter is teams who have isolated themselves by their tools. I’ve seen tech writing teams using specialized or unnecessarily complex authoring tools, often because someone on the team has invested years using it and don't want to change. They're often blinded by their own expertise. That can be a very difficult and expensive obstacle to overcome.

Also related to that is lack of using a common enterprise content management platform to share content with other content-producing teams like marketing or training. When you can’t share content between other departments because everyone is storing their content in different places and using a different authoring application or file format, you create inconsistency, duplication, redundancy, and anarchy. In large organizations, that’s probably the most common and most expensive issue you’ll find and only the smartest and most organized companies can resolve this.

Steve Bain is a Technical Communication Consultant based in Vancouver, Canada with experience in content strategy, customer success, and instructional design for various technology industries.