Mobile and Agile: The Floating Writer's Survival Kit

By Alyssa Fox and Meredith Kramer

Contents

Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

• Introduction
• Making the Transition
• Gaining Clout on the Product Team
• Planning the Release
• Creating User Stories
• Planning Iterations
• References

Introduction    

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    

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.

New Terminology

Agile development uses specific terms. Some of these terms and their descriptions are below.

Agile development

A development process that promotes iterative development, testing, and documentation of each feature/function.

Scrum

An agile development approach that emphasizes close communication through daily stand-up meetings. Scrum is intended to increase speed and flexibility in the development process.

Scrum master

The team member who facilitates scrum meetings and works to remove blocks that prevent team members from proceeding with their work.

Iteration

A short period of time in which a full software development cycle occurs: planning, design, development, testing, and documentation. Iterations typically last from 1-4 weeks. The goal is to have a potentially shippable product at the end of each iteration.

Backlog

The repository for all requirements and wish list items for the project. It is useful if the backlog contains rough estimates for the items to help with prioritizing during regular planning and review times.

Capacity

The maximum amount of hours a team member can work on a project during one iteration.

Design Documents

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:

• QE and Development no longer have to review an entire book (or more) during one of the busiest times of the release cycle.
• Info Dev gets more thorough reviews since QE and Dev have more time during each iteration to review pieces of the documentation.
• The documentation is more technically accurate, and therefore of a higher quality, due to the more thorough reviews.
• The floating writer's capacity needed for an approval draft is reduced because most of the work has already been done in previous iterations. Therefore, if you have multiple books on multiple products, there is not as big of a hit all at once on your time.
• Since you are likely moving writers around on an iteration-by-iteration basis, if you need to bring someone in to work just on the approval draft, they have a more complete document with which to work. It will then take less time for you to train them to pick up the work, and less time for them to get up to speed and get moving with the work.

Gaining Clout on the Product Team    

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.

Speak Up!

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."

Be Involved

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:

• Show an interest in the requirements, design, and thought behind the design of the product.
• Attend any and all release and iteration planning meetings. If you aren't being invited, invite yourself.
• Offer to help improve text in the GUI. At NetIQ, our Info Dev team is responsible for all text that shows in the product. Often it just takes some informational text or a better field name for the GUI to be much less confusing to a user.
• Be a usability advocate. Look at things from the user's perspective. Something may be completely clear to the developer, but that doesn't guarantee it's the best way to present it to the user. For example, a developer might code a window that asks if you want to automatically notify a user when a report has completed, and your choices are "True/False" instead of "Yes/No."
• Have the writer working on the feature interact with the developer and/or QE person working on the feature. Don't funnel all information through one person.

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.

Planning the Release    

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.

Creating User Stories    

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:

• Independent: Can be worked on without pulling in other stories, can be scheduled in any order
• Negotiable: Allows flexibility with engineering team, implies it is understandable (easy to pick up)
• Valuable: Frames stories from customer perspective
• Estimatable: Allows lead/manager to pull floating writers on to project based on their capacity and estimate of time needed for story
• Sized appropriately: Lets floating writers focus on smaller pieces and move on and off project more smoothly
• Testable: Lets floating writers see upfront what the feature is supposed to do and can write more thorough documentation

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:

• Specific: Helps in understanding and prevents overlap
• Measurable: To know when it can be marked as complete
• Achievable: Is it feasible and realistic?
• Relevant: Aimed at fulfilling the story
• Time boxed: Estimated work remaining. Will it be done within the iteration?

Planning Iterations    

When planning an iteration, determine the length of the iteration and the workload capacity of each team member.

Determining Capacity

When determining a team member's capacity, keep the following items in mind:

• Consider previous iteration estimates, if available.
• Include vacation and non-iteration responsibilities, such as meetings, customer support, and so on.
• Do not include the first or last day of the iteration.
• Ensure Development finishes early so Quality Engineering and Information Development have time to complete their user story tasks before the iteration ends.

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.

References    

1. http://www.agilemanifesto.org
2. http://xplanner.org
3. "Managing Information in an Agile Environment," Robert Armstrong, Natalie Dyen, Ellen Pillsbury. Presentation at 53rd Annual STC Conference, May 2006.
4. "Agile and Doc," Toni Taliaferro. Presentation at 53rd Annual STC Conference, May 2006.
5. "Surviving as a Technical Writer in an Agile/XP Environment," Andy Sutton, Matt McDonough. Presentation at 53rd Annual STC Conference, May 2006.
6. Subramaniam, Dr. Venkat. Agile Developer Training Manual. September 2006.

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
NetIQ Corporation
1233 West Loop South Suite 1800
Houston, TX 77027 USA
713-418-5334

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
NetIQ Corporation
1233 West Loop South Suite 1800
Houston, TX 77027 USA
713-418-5400

Conference Fees [online-registration]

The Conference fees for each person attending are based on attendee classification and registration date: