Technical writing: Is your company harnessing the power of Help documents?

A large number of engineering and software companies, especially start-ups and medium-sized firms that matured quickly, struggle to come up with a strategy for documenting new features and bug fixes.

In a culture of rapid expansion, company managers often neglect to define work processes and formalize departments, so it’s not surprising that documentation becomes collateral damage.

The core of the problem is that scores of managers do not take the time to define a clear link between the company’s bottom line and documentation, so it naturally follows that Help gets pushed to the bottom of the task pile.

And that isn’t all.

The fast-paced technology changes make it difficult for managers to mitigate this problem, and capture opportunities through Help manuals. Perhaps the biggest challenge managers face is making sure features are documented in time to generate value for clients before being obsolete.

Furthermore, taking the time to schedule interviews with professional writers is time consuming, which is why technical writing is often done by engineers and software developers on the go. Or when pressured from management when far too many clients complain about poor updates.

In other words, when it’s already too late.

Having clients complain about bad Help documents should be a red flag for any manager hoping to keep clients. Because failing to retain clients can cost companies important business and really hurt their bottom line.

Here are a few ideas your company can implement to boost dialogue with clients (“Help us help you”) and ensure Help documents generate value for clients:

Turn Help into a marketing tool for building client relations

Recognizing the need to raise the external profile of Help documents is the first building block of the technical writing process, especially for start-ups and medium-sized companies still grappling with growing pains.

After all, Help documents are only as good as the frequency clients rely on them to use technology effectively.

Here are a few practical steps companies can take to turn Help into a marketing tool for bolstering relations with their clients:

  • Notify clients about Help updates as soon as they are put online.
  • Incorporate Help updates into your company’s social media presence on a regular basis.
  • Ask for client feedback through surveys and online tools.

Build trust between subject matter experts (SMEs) and the writer

Employees with technical backgrounds and writers come from different worlds and the relationship can often feel like a cultural clash. (You don’t know what a Command Line Interface is?).

Unless both sides see value in their communication, the end result will not yield any benefits – neither for the company nor the clients.

The following suggestions may go a long way in improving the climate in which Help is written.

  • Establish a weekly timetable for interview slots with programmers or testers.
  • Create a schedule for meeting between managers and the writer for prioritizing workflow tasks.
  • Communicate that Help documents and the interview process benefit the company in the long run.
  • Promote a collaborative effort  between SMEs and the writers during meetings, newsletters and other company announcements.

Incorporate Help into the company’s corporate fold

Before you can generate value with your Help documents, you must turn your company writers into one of your company’s internal partners. In doing so, check out the following practices designed to help you boost the legitimacy of the writing process in your company:

  • Include writers in your scrum meetings.
  • Create a schedule for interview meetings between the SME and the writer.
  • Allow the technical writer to research the functionality by reading specs and other documents, and testing the functionality ahead of the interview.
  • Make sure the writer interviews the SME in a conference or meeting room to minimize walk-by distractions.
  • Enable writers to conduct the interview with a tape recorder and online recording software to:
  • Ensure clarity
  • Minimize the possibility of going back to the SME with any questions
  • Maximize time efficiency of the SME and the writer


Keep in mind that spearheading the initiative and ensuring project deliverables are being met will not be without a snag or two. Take a look at some of the challenges you may anticipate during the process of improving your Help documents:

  • Turning things around takes time: programmers are busy and need convincing Help documents are important.
  • Some programmers aren’t comfortable with presenting functionalities due to bugs and glitches.
  • Office culture shifts are often met with opposition.
  • Some SME interview subjects are better than others.
  • There are no quick fixes.




Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s