A Technical Writer's Role in Development Methodologies

There are two basic development methodologies that most companies utilize:

The Waterfall process (Sequential) or The Agile (Iterative) process. These basic models exist to ensure that project deliverables are met within a given time frame, to keep projects on track and progress towards completion. A technical writer’s role in a Waterfall or Agile development methodology is to produce documentation that coincides with company products, such as a given software.

A documentation plan with room for changes to accommodate the ever-changing list of priorities in project deliverables is recommended. First, a general understanding and planning of how to achieve final documentation will help a technical writer succeed in any work environment.

Documentation Development Process:

There is a general approach to developing supporting technical documentation for any company product:

1. Gather Information

• Learn about the subject matter (the product) by reading existing product literature, specifications documents, engineering documentation

• Use the product to gain an understanding of its purpose, services and user needs

• Understand your audience and how they will go about using the product by conducting research and formulating a User and Task Analysis Report

• Interview Subject Matter Experts (e.g. software engineers) to thoroughly understand how the product works

• Listen attentively and take notes when attending all product training sessions and team meetings regarding an upcoming product launch

2. Plan and Organize the Information

• Determine what the final deliverables are based on product user needs

• Create a schedule for documentation completion with realistic and achievable milestones

• Create a documentation plan

3. Start Writing

• Create a rough outline of all topics to be covered in the documentation complete with second and third level headings to start organizing information in a logical manner

• Start Writing and create placeholders for information or graphics that require further research for accuracy and inclusion in the documentation

4. Verify Your Work

• Test your documentation to ensure it meets users’ needs

• Proofread for logical flow of information and sensible visual presentation of documentation content

• Ask for feedback and constructive criticism from Subject Matter Experts on what can be improved upon

5. Revise and Improve

• Edit documentation for grammar and punctuation

• Rewrite content in simple English to create clarity

• Re-organize content to make it easier for users to find information

• Send the revised documentation out for peer review or review by Subject Matter Experts Again to gain approval

Technical Documentation exists to be released and then maintained-constantly revised with updates including new product information. Realistically, developing documentation is a reiterative process where previous steps are almost guaranteed to be revisited.

Sources:

Laan, Krista Van, and JoAnn T. Hackos. The Insider's Guide to Technical Writing. O'Reilly, 2012.

“Technical Writer.” Writing User-Centered Documentation, or, My Best Days as a Technical Writer, I'd Rather Be Writing: Exploring Technical Writing Trends and Innovations, 21 June 2012, idratherbewriting.com/2012/06/21/writing-user-centered-documentation-or-my-best-days-as-a-technical-writer/.