Do we need technical writers anymore in this new world of agile? Of course. Internal integration and sales folks still need accurate and readable documentation. There are still documentation needs in the areas of regulatory processes and federal requirements for organizations within fields such as health care, state and local government, and finance. And there is still, and always will be, a need to provide avenues for customer self-help in order to decrease the burden on customer support.
But where do technical writers fit in this new paradigm?
To be successful, technical writers must become part of agile teams. This is a departure from the old way of thinking about the separation of teams and responsibilities. No longer can technical writers wait in a different department for robust requirements documents or massive release updates, because none of those things exists in mature agile organizations.
As most IT departments and CTOs are striving to move their teams to a mature agile process, technical writers must adapt as efficiently and effectively as the development personnel. This new agile process demands that knowledge and information dealing with software or product releases are only sparingly documented up front, making the technical writer's job of gathering information much more challenging and dependent on talking with people over reading requirements. Not only has the technical writer’s place in the world changed, but how and where to document has changed as well.
Documentation in an Agile Development Cycle
The days of verbose user manuals written in Microsoft Word or other static word-processing software are over. Now, technical writers must learn to be as adaptive and agile as their development counterparts by writing in XML-based tools and staying ready for the next change. The only effective way to stay abreast of these changes is to be part of the agile team; however, it is also important to keep the documentation as changeable as the requirements.
Today, there are many XML- and topic-based authoring tools that enable technical writers to document in reusable and easily edited chunks of knowledge. Software such as MadCap Flare and Adobe FrameMaker are a couple of examples. The benefit of creating reusable content is that if a requirement changes (which happens all the time with the agile process), the technical writer can make the change in one place instead of having to search countless documents and change each one individually. This type of documentation also makes content review more manageable within the time confines of a one- or two-week sprint cycle.
Another trend in documentation that takes the agile process into consideration is the advent of context-sensitive help. This type of help provides small chunks of information that is related to the immediate needs of the user. It is usually interwoven within the user-interface code of the application and available on demand or within a help tour. Again, because context-sensitive help is part of the development process, it’s crucial for the technical writer to be part of the development process.
Keeping documentation light and reusable is only part of the answer to keeping technical writers engaged in the new agile approach. Communication within the development team is also paramount. It is now the technical writer’s responsibility to engage and elicit feedback in every part of the development lifecycle, from daily standups to sprint reviews, user acceptance testing, and final product signoff.
The Technical Writer’s New Role
Because agile prefers team collaboration over heavyweight documentation, the modern technical writer needs to be part of agile teams and closely aligned with the ceremonies and deliverables contained within sprints. Writers should attend and participate in each ceremony for which they may have deliverable responsibilities.
These meetings are the lifeblood of an agile process because product owners, developers, and engineers make most of their functionality decisions during these collaboration sessions. Someone must be there to document decisions; these are the new requirements in the agile world. In addition, most team and customer documentation needs will present themselves within the standup and sprint review or demo meetings.
Becoming part of the development team requires effort by the technical writer. The first step to this transition is for the writer to attend the daily standup meetings. Although not every decision or conversation about technical jargon may be of importance to the writer, it is of the utmost importance that the writer be present to build relationships with and ask questions of the development personnel. The sharing of information and building of rapport among the development team members is a key part of the daily standup, and it also serves as a key engagement point for the technical writer.
The sprint review meeting generally takes place at the end of every sprint. It gives all stakeholders, including customer service, product, and development, the opportunity to see what has been completed during the sprint and what will most likely be delivered to the customer either immediately or in the near future. This meeting provides an opportunity for the technical writer to document not only document what has changed through the demos, but also stakeholder feedback for use by the development team.
Attending agile ceremonies and becoming part of the development team is the logical way for technical writers to fit into this fast-paced and adaptive new way of creating products. The answer to the question of what is required for technical writers to fit into the agile process is the same as it is for all other members of the development team: They must be able to adapt.
About the author
Robert Spielman has a Technical and Professional Writing degree from Metropolitan State University. Rob has many years of experience as a developer, quality assurance analyst, and technical writer with a variety of companies in the Minneapolis, MN area.
