- Embedded assistance
- The technical writer's role today
- Redefining quality technical information
This chapter is from the book
This chapter is from the book
This chapter is from the book
The technical writer’s role today
Our roles as technical writers are evolving as quickly as the products that we write information for. Because we develop embedded assistance, the timing and ways that we work with our extended teams have changed. We are more involved with product design and user interface development, which means that we must be involved earlier than ever in the development cycle.
As discussed in “Embedded assistance” on page 4, the separation between product and documentation is an artificial one, in large part a result of the historic waterfall development processes. The waterfall development process is made up of specific phases in which each participating team finishes its work and hands it to the next team. The problem with this process is that downstream teams have very little chance to change anything that happened upstream. Furthermore, because documentation is developed close to the end of the cycle, documentation often tries to describe poor design that can no longer be changed. Too often, technical writers who work in a waterfall development process must write comprehensive documentation that needs to atone for unwieldy design.
More and more development teams are using an agile development process, which depends on cross-functional teams working together throughout an iterative development cycle. Although members of these cross-functional teams all bring their own skills to the team from their unique disciplines, they are much more likely to look at and contribute to each others’ deliverables so that products are a full team effort. Agile development, as the name implies, lends itself to making quick changes to product design when necessary.
In agile development, writers have a particularly effective role as the users’ advocate. The Agile Manifesto (agilemanifesto.org) values “individuals and interactions over processes and tools” and “working software over comprehensive documentation.” Writers who work on a project that follows the agile development process are critical members of the team throughout the entire process, from the earliest design phase, before a single line of code is written, to the final fit-and-finish stage. By participating in the design process in partnership with product developers, usability engineers, visual designers, and customers, writers can promote clear interaction and wise use of embedded assistance, thereby reducing or eliminating the likelihood of “papering the product” with unnecessary documentation.
The guidelines in this book describe the characteristics of quality technical information. However, your role in developing information and, indeed, in developing the product, is as important as any of the guidelines. Rather than trying to explain problems with the product design after the fact, focus on fixing real-world problems that users have.
When you develop quality technical information, you are responsible for:
- Knowing the user stories, which are the goals that users need to accomplish by using the product
- Being the users’ advocate, ensuring that the product employs the necessary programmatic assistance and embedded assistance
- Owning the words, whether they are in labels in the user interface, error messages, or topics that are separate from the product