Mobile and Agile: The Floating Writer's Survival Kit
Click a link below to jump to a particular section; click any "
Agile development is a popular methodology used by software companies. When making the transition to agile development, technical writers can face several challenges when floating among multiple project teams.
As a floating writer, gaining clout and presence on your product teams is essential to success on those projects. Making your teams aware of your interest and need for information helps them remember you when you are working on another project.
Release and iteration planning is always vital in agile development environments, but even more critical when dealing with multiple projects.
Agile development was developed for in-house products, and then adapted for use by software companies. Originally, the methodology did not include documentation, but many organizations have figured out how to use it effectively and adapt it to their needs. However, even when product teams use this process successfully, it assumes you have resources dedicated to each team.
Businesses today are cutting back and doing more with less. People have more to do and less time and budget with which to do it. In software companies, one way this can manifest itself is in resources moving among multiple projects. When we began using an agile development process, we searched far and wide for information about how to work using that process when working on multiple teams. What we found was that most of the writers out there working with agile development were dedicated to one product team. As floating writers, we have unique challenges in agile development.
At NetIQ, the members of our Information Development team move from product team to product team. We have leads on a few product teams that generally don't move around, but for the most part, our team members work on at least two projects simultaneously. While the flexibility of our team members can be beneficial, it can also be challenging to plan for and execute work on multiple teams. This paper describes how technical writers can smoothly transition to and continue to use scrum agile development when they float among several cross-functional project teams.
Making the transition to agile development takes time. Regardless of which development process you're currently using, it will likely take several iterations, and possibly even a release or two, for your project team to feel comfortable with the new processes and way of life.
Agile development uses specific terms. Some of these terms and their descriptions are below.
While agile development de-emphasizes design documentation in favor of working software, by no means does that mean all documentation is done away with. Comprehensive specification documents are replaced with shorter, more fluid documents such as user story documents and paper prototypes. Agile development involves working closely with customers to ensure you are developing what they ask for, and allows for refinement and rework along the way. A user story document describes what the user story is to do, acceptance criteria for the user story, and any additional information useful to QE and Info Dev.
When writers move on to a project for an iteration or two, they can get bogged down in a lengthy and sometimes complex spec. It's much easier for them to pick up three or four user story documents to read that apply just to their assigned user stories.
Adapting Your Review Cycle
When we used the waterfall process, we used a review cycle that included three drafts of each book: a first draft, an approval draft, and a quality edit draft. The first draft and quality edit draft were internal to Information Development. All of these drafts happened toward the end of a software release cycle, and were not reviewed by anyone outside the Information Development team until the project was feature complete and all features were documented in one fell swoop. Unfortunately, the time when we sent out our approval draft for review by other functional areas such as QE and Development often coincided with their busiest times of the release cycle--testing the product and fixing bugs.
With agile development, we now write documentation for a feature in the iteration it is developed and tested. On more mature products, we no longer send out the entire book as a first draft for ID review. Each time a feature is documented, that documentation must be reviewed by the ID lead/manager and by QE for technical accuracy before the team can close the user story. We still send out approval drafts, but for most reviewers, at that point it is simply a chance for them to see the book in its entirety, since they have reviewed all the new and updated parts of the book previously.
The benefits to this approach include the following:
Agile development relies heavily on frequent and clear communication. It might seem like communication will not be an issue for us because we are professional communicators. However, often essential communication is thwarted by preconceived ideas of what a technical writer does or can contribute to the team.
It is imperative you speak up in meetings and take the initiative to get involved in all aspects of the product development. Ask lots of questions. If you see something in a design meeting that doesn't make sense to you, or you think there's a better approach, say so. Don't be intimidated by the fact you're not a developer. It's our job to look at the product from a user's perspective. If a GUI is difficult to use, let the developer who's coding it know. If you find out planning meetings are happening without you present, talk with the ones holding the meetings and make sure you're invited in the future.
Scrum meetings are your chance to communicate with Development and QE on a scheduled, regular basis. It is important to give and get detailed, specific information during these meetings. If you don't receive the information you need, ask direct questions to solicit greater detail.
Sample Scrum Topics
For example, saying, "I'm working on the User Guide" in a scrum meeting is not detailed enough. A better description might be, "I'm creating a new chapter in the User Guide for Feature X. I've talked with Development and received all the information I need to complete the draft, but will go back to them tomorrow for them to take a look at what I've got to ensure it's technically accurate."
Another example of a vague scrum topic is saying, "I'm creating the help for Feature X." This statement does not provide enough information or let anyone else on the team know if you need help or additional information. A better description could be something like the following: "I am about done creating the help structure for the wizard Feature X uses. Developer Sally, I'll need to get with you to show you what I did in the mapping file so we can hook up the help to the wizard page code. I'm also adding these topics to the .chm file's table of contents."
Being involved in all areas of the product development is crucial to your success as a writer on an agile development team. This level of involvement ensures you are tuned in from the beginning and know the requirements, design, and thought behind the design of the software. Not only does this make you a more informed writer, it shows the other functional teams (Development, QE, etc.) you are serious about learning the product itself and gains you invaluable respect.
Ensure you're involved in the following ways:
Take Ownership of Technical Accuracy
At NetIQ, the writers are responsible for the technical accuracy of the documentation they write. In order to take ownership of the technical accuracy of your documentation, there are a few key things to keep in mind. First, don't write just what the developers tell you to write or assume something works a certain way. Ask questions and gain your own understanding of how the product works.
At NetIQ, the Information Development team creates and maintains its own set of virtual machines on which we install and test the builds of our products. Owning our own installations of our products allows floating writers to quickly and easily access the product without waiting on QE to install the product for us. This quick access reduces the amount of time it takes someone to jump in and start learning the product.
You must understand the product to know if there's a technical or usability problem in the product. If you demonstrate a solid understanding of the product, the team trusts you more when you make a suggestion for change.
Serve on a Core Team
A core team consists of a lead from each functional area (Product Management, Development, QE, Info Dev, and Technical Support). The core team drives the project and serves as a system of checks and balances to ensure there is equal representation from each area. The core team makes the decisions for the project together.
When planning a release, think about your entire review cycle. The First Draft and Approval Drafts will coincide with active Development iterations, whereas the Quality Edit should occur during a hardening iteration so it doesn't affect Development and QE schedules.
Do resource planning on an iteration by iteration basis. Have a manager or lead look at resources across projects in order to provide the optimum load balancing.
User stories define a software system requirement, or what you are building. When creating a user story, include enough information for all functional team members to perform their tasks.
Creating Good User Stories
When creating user stories, use the INVEST method to ensure the stories are ready for all stakeholders to begin working with them:
User Story Tasks
Tasks are broken-down items of work required to fulfill a user story. All tasks must be completed before you can close a user story. To ensure tasks are clearly defined, follow the SMART method:
When planning an iteration, determine the length of the iteration and the workload capacity of each team member.
When determining a team member's capacity, keep the following items in mind:
When you serve on multiple teams, you could spend 4-5 hours per week in scrum meetings for each project on which you're working. Work with your lead or manager to spread out the workload in such a way that you can delegate scrum meeting attendance to others. Another option is to attend only the scrum meetings that pertain to your highest priority project at the moment. You can also ask the scrum master to send scrum status reports through email to help those who are unable to attend each scrum meeting for each project. While it's preferred you attend each scrum meeting for each project on which you work, sometimes it just isn't possible. Gaining clout and a presence on your team is that much more important in situations like this so people don't forget you when you're not there.
Sizing Documentation Work
You can create more accurate estimates by applying a standard number of hours per page of documentation written based on the level of source material. For example, if a task requires one new page of documentation with little source material, the task will take 6 hours. If you need to rework a page of documentation with some source information, it will take 4 hours.
Using a formula to estimate documentation work can make iteration planning much easier. You can plug in your tasks based on the information in the user story to quickly estimate the amount of documentation work required to complete your tasks. You then compare the number of hours required to complete all documentation tasks in the iteration to the total hours of documentation team member capacity.
Alyssa Fox is an Information Development Manager at NetIQ Corporation. She works across product teams to coordinate resources, processes, and schedules for agile planning and implementation. She received a B.A. in History from Texas A&M University and has been involved in technical communication for over 10 years. Alyssa enjoys projects that address the entire user experience from beginning to end, and has an avid interest in usability. She is also interested in developing junior team members and building cohesive, cross-functional teams that work together to deliver a product that is relevant to the user. Alyssa is a senior member of STC and has served the Houston chapter as Executive Vice President, Vice President of Competitions, Vice President of Hospitality, Banquet Manager, Banquet Arrangements Manager, and competition judge. Alyssa has spoken at STC Houston chapter meetings and has won awards in the local STC competition.
Alyssa Fox, Information Development Manager
Meredith Kramer is a Lead Information Developer at NetIQ Corporation. She started her technical writing career after graduating from Texas A&M University in 1998 with a B.S. in Journalism. Meredith enjoys contributing to projects that provide information to users in a clear and concise way to help make their jobs easier. She has served on teams this year that have moved from the waterfall methodology to agile methodology and spearheaded efforts to promote Information Development in that transition. Meredith is a senior member of STC and has served the Houston chapter as Vice President of Hospitality, Technical Publications competition judging manager for the past two years, and competition judge.
Meredith Kramer, Lead Information Developer