Managing the Agile Technical Writer
Introduction
As agile software development gains popularity and corporate budgets are tight, technical publications managers are becoming obsolete. In many organizations, the Director of Software Development or Director of Product Management takes responsibility for managing the writing staff. In many cases, these managers lack formal training and experience in creating publications and managing writers. This article is a guide for managers who lack experience in managing writers, but are responsible for ensuring the documentation is delivered.
To manage agile technical writers, it is important to understand how the waterfall and agile documentation development processes differ. This article assumes that you are following a pure agile software development process, as opposed to what I like to call “agilefall,” which is a mixture of waterfall and agile methodologies.
The Waterfall Process
When an organization follows a waterfall process, the writer and manager might receive one or more of the following documents: Market Requirements Document (MRD), Functional Requirements Document (FRD), and a Product Requirements Document (PRD) when the project begins. Using these documents, the manager and lead writer work together to create a project plan that defines the scope, cost, resources, and schedule. At this time, the writer usually installs the product build, which is typically in an Alpha state. Furthermore, the manager or lead writer creates a documentation plan that includes the deliverables, scope, translation plan, resources, risks, assumptions, dependencies, build and source control details, and schedule.
When the writing process begins, the writers interview subject matter experts and then “go into their caves” and emerge several months later with a help system and/or printed documentation in the form of a draft. Normally, a weekly status report is delivered to the manager. When the documentation and product are close to completion, the documentation is delivered to developers, quality assurance, product management, and editing staff for technical and editorial review. Some organizations require a formal inspection of the documentation to ensure complete technical accuracy. After the team members return their reviews, the writers incorporate the changes and subsequently create final builds. For printed documentation, the writers work with a printer to coordinate the final book production.
The Agile Process
When an organization follows an agile process, formal documents such as MRD, FRD, and PRDs are typically not available. These documents might be replaced with shorter “mini-specs” that describe each user story or requirement. Photographed white board sessions also serve as “mini-specs.” Larger organizations with several dependencies (such as translation, support, and marketing) might choose to create documentation plans, while smaller organizations do not require this level of detail.
Agile teams work in iterations, which are short time boxes such as two, three, or four weeks. A typical agile team consists of a scrum master, product owner, software engineers, QA engineers, usability engineer, and a technical writer. The team delivers working, tested, and documented code at the end of each iteration.
Typically, at the beginning of each iteration, the team holds a planning session. If the agile team does not have a dedicated writer, but instead a “floating writer,” the manager might attend the planning session instead of the writer. During the planning session, the user stories are sized. The sizing should include the estimation of documentation work. This point is important because one user interface change that takes five minutes of coding could require days of documentation rework.
Agile teams participate in daily standup meetings. Writers attend daily standup meetings, and they report the specific details about the progress of the documentation for the user stories on which they are currently working. At the end of each iteration, typically a review session and retrospective occurs. In some organizations, the writer performs a demo of the completed documentation at the sprint review.
As opposed to a final review of the documentation at the end of the release as in waterfall, at least one member of the team completes a review of the documentation for each user story during each iteration. Editorial reviews are performed at milestones during the release or near the end of the release.
Tips for Managing the Agile Technical Writer
- Structure your teams to have a dedicated resource on each agile development team, if possible.
- Reduce the amount of management required by encouraging self management practices, for example do not assign tasks. Allow writers to choose their tasks.
- Encourage writers to evaluate each user story and identify the documentation changes that might result. Keep in mind, some writers from traditional waterfall methodologies are accustomed to managers assigning their documentation tasks.
- Verify that writers are following an established style guide and any guidelines established by information architects.
- Mentor or assign mentors to junior writers.
- Do not deprive technical writers of information. In some organizations, lead architects’ time is considered so important that writers are not allowed to ask questions. This impedes progress.
- Consider that the documentation is part of the product, not an afterthought.
- Consider that the agile process does not always allow for editing and overall reviews. Scheduling a “hardening sprint” at the end of the release cycle allows writers to test procedures, check indexes, and complete final edits.
- Encourage team members outside of the writing staff to participate in the review process.
- Ensure writers are working in parallel with development. Encourage “mini-specs” and ensure writers are involved in planning and design sessions.
- Ensure writers complete their tasks at the end of each sprint. If parallel work streams are not possible because of the nature of the product, ensure writers complete their tasks at the end of each subsequent sprint.
- If writers consistently miss deadlines, re-evaluate the sizing of user stories.
- Ensure a manager or writer attends an after hours standup meeting at least once a week if development teams are offshore.
- Ensure translation managers are kept up-to-date with project deliverables or assign this responsibility to a lead writer.
- Encourage writers to use source control instead of creating and building documentation on their local machines.
- If there are several writers on separate teams across a large organization that have cross-product dependencies, encourage members to meet at least twice a month to keep each team on top of project progress.
- When developers are focused on “back-end” work that does not affect the end user of the product, encourage writers to edit documentation, enhance indexes, and test procedures.
- If your team uses a WIKI to communicate team practices, encourage writers to develop information for it.
