Tech & Work

The hidden relationship between project managers and technical writers

Want to know the secret to better quality documentation and improved software design? Will Kelly outlines how the key is an effective relationship between PMs and tech writers.


The quality of project management has a direct impact on technical documentation, a fact that is often overlooked by project managers and even the technical writers. This article looks at the areas where the relationship between project management and technical documentation intersect. Understanding these key points along the project timeline can help improve both the quality and effectiveness of your technical documentation.

Put a plan around a project or a project around a plan
Technical documentation will suffer if the project is floundering around without a project plan. A project that does not follow a plan is at risk due to a number of scenarios, including:
  • Reverse-engineering technical and business requirements after the product is already developed or is well under development. These requirements may indeed pass the muster, but the lack of formal requirements elicitation from customers can cause problems later.
  • Reverse-engineering functional specifications after the product is already developed or is well under development. While these specifications are often necessary for quality assurance and other purposes, the reverse-engineered functional specifications may still lack customer focus.

Other project-planning elements that impact technical documentation include:
  • Insufficient customer contact, resulting in the development team not being truly knowledgeable about the customer, the customer’s business, and the business reasons behind the development effort.
  • Disregard for any sort of a software development life cycle.

While technical documentation cannot compensate for the lack of a plan, it can be instrumental in reviving a troubled project. This method of catching up through documentation is going to extend timelines, but will serve the project better by mitigating some risks and strengthening the overall product through documentation analysis.

Where the process and Gantt charts don’t meet
Even experienced and technically savvy technical writers get frustrated when the project timeline isn't accurate or feasible. While some of the technical documentation development and management methodologies touted by technical communications experts are not cost feasible, neither are instantaneous deadlines that sacrifice documentation quality and lead to frustration among internal parties and, eventually, frustrated external customers. The result: a slew of cost issues arise. Consider the following when scheduling the technical documentation elements of your project:
  • Involve the technical writer(s) assigned to the project to help plan the timeline for documentation.
  • Writing is not an instantaneous process and, much like coding, analysis and related development efforts have their own process and timeline requirements. It’s best to work with the writers assigned to your project to maximize their benefits.
  • If the timeline is tight, develop a list of priorities of what absolutely needs to be documented in order for users to adopt the product.

A typical breakdown for a technical writing project includes:
  • Research time to learn the software and other elements, such as the underlying technology and related issues, that are required for the documentation effort.
  • Dedicated time for writing.
  • Dedicated time for editing. Specifically, copy editing and editing for style, clarity, and other issues.
  • Dedicated time for a review of the technical accuracy of the documentation. Even in cases where technical writers are trusted to ensure technical accuracy, there still needs to be a modicum of review time built into the schedule to go over the document with fresh eyes.
  • Production time to output the documentation in a format for final delivery to customers—whether the format is print or electronic. If you are using an outside printer to fulfill documentation printing, then you’ll need even more time to ensure that a third-party printer can produce the hard-copy documentation.

Obstacles to documentation
Is there such a thing as a product that can’t be documented? Many people will answer “No.” However, immature user interfaces and application workflows can make documentation efforts more difficult, thus affecting documentation timelines.

User interface prototyping and other processes such as storyboarding ensure a consistent user experience and flow, which is always easier to document and which results in enhanced usability for the customer.

Allow sufficient ramp-up time
Technical writers need sufficient ramp-up time to become versed in the product you are tasking them to document. While ramp-up time is relative depending on the writer, here are some things a project manager can do to support the writer who is beginning a project:
  • Provide ready access to necessary hardware and software so the technical writer doesn't have to waste time waiting on equipment required for documentation projects.
  • Ensure that necessary system access, usernames, and passwords are provided so the technical writer can access the systems he or she is tasked to document.

Allowing technical writers sufficient ramp-up time is more than just a learning curve; it’s about getting the resources in place so they can perform their jobs with minimal downtime, which is billable when they are on-site waiting for corporate bureaucracies to deliver the resources they need.

Review the reviewers
While technical writers must have a stake in the technical accuracy of the documentation they produce, there is often a need for technical reviewers to review the documentation. This review time needs to be taken into account in the overall project schedule, including:
  • Scheduled time for technical staff, project managers, and other reviewers to go over the documentation.
  • Time for the technical writers to add the revisions to the documentation.

Can project managers and technical writers get along?
The technical documentation component of a software development project does require input from technical writers to help ensure quality technical documentation. A working collaboration between project managers and technical writers can help organizations reap the benefits of better software design (because it’s documented), and better customer support through documentation. A self-sufficient customer who doesn’t call customer support is like money in the bank for your company.

 

What do you think?
How well do project managers and technical writers work together in your organization? Post a message in the discussion board below or send us an e-mail.

 

Editor's Picks