Editor’s Note: In the first of a series of articles on Agile and tech comm, Alyssa Fox outlines the common challenges writers face on traditional development and Agile teams, and shows us why Agile can be the better approach for technical communicators.
Technical communicators have historically faced several challenges when working on development teams. From not receiving the information needed to do their jobs, to ensuring their work estimates are included in the overall team’s estimates, to showing their value to stakeholders, writers on project teams can feel like they are facing an uphill battle to create good documentation.
A number of factors can influence how these challenges manifest during product development, including organizational culture and various business needs, and the agile development approach can help. Agile is an increasingly popular development method primarily used by software companies. Its iterative nature and focus on the self-directed team support writers’ attempts to expand their roles on project teams, improve the quality of their deliverables, and avoid most of the end-of-release-cycle crunch that typically results from a traditional waterfall process. No matter if your employer has joined the agile movement, or if you still work in a 20th-century waterfall world, or some hybrid of the two, you can recognize and learn to rise to the challenges common to most development teams.
Being an Equal Part of the Team
Most technical writers with more than a few years’ experience under their belts can empathize with the struggle to be included as an equal member of the project team. The business case for this model is simple and common sense: Being treated as a vital part of the team leads to increased communication with other team members, inclusion in essential meetings, and improved product knowledge—all of which contribute to better, more effective documentation and user support.
Regardless of the type of development environment you are in, to be an equal player, the onus is on you. Take the initiative: speak up in meetings, request invitations to those meetings, offer feedback—in other words, get involved in all aspects of the product development. This level of involvement tunes you into the project from the beginning, with obvious benefits: knowing the requirements, design, and thought process behind the design of the software. Ask lots of questions—lots and lots of questions—but make them count. If you hear 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 that you’re not a developer—chances are the product manager and the marketing team know less about code than you do.
Remember, it’s the technical communicator’s job to look at the product from the user perspective. If you find a user interface is difficult or confusing, so will users, so you have an obligation to provide that feedback to the developer who’s coding it.
Agile development focuses on communication and collaboration, being an equal member of the team requires you to speak up and contribute. (Photo credit: David Boyle in DC, via Flckr)
To be an equal partner on the engineering team, you must own the work with the same level of commitment as developers, analysts, or testers. Claim ownership of the technical accuracy of the documentation you write. Don’t write just what the developers tell you to write or assume something works a certain way. Work with the builds, ask questions, and gain your own understanding of how the product works. That means speaking up to get access and then maintaining whatever virtual machines or environments you need to so you can quickly and easily access the product. If you demonstrate a solid understanding of the product, the team trusts you more when you point out a technical or usability problem and make a suggestion for change.
Agile development focuses heavily on communication. The feature requirements, use cases, and test plans of a waterfall environment translate to user stories, acceptance criteria, and acceptance tests in an agile world. An agile process uses significantly less project documentation, with the idea that the communication going on among the team members is enhanced through several different types of meetings. While the number of meetings might seem overwhelming at first, it quickly becomes apparent how crucial they are for open discussion about the user stories and planning items the team is working on. Become more visible by participating in these meetings, and you’ll gain both the trust of your team members and more product knowledge. That product knowledge directly feeds your ability to produce higher-quality content that provides information that users really want.
Getting Helpful Documentation Reviews
Whether you are in a traditional or agile development environment, getting valuable, informative edits on documentation you send out for review can be like pulling teeth. Some reviewers give the documentation a cursory glance and declare it “okay” with no helpful comments. Others fail to follow the steps as listed in the documentation when testing procedures, and have no way to ensure the writer captured everything accurately.
Agile sprints are like filmaking daily rushes… a chance to review the work and close out the user story before moving onto the next sprint (image courtesy of Miquel Angel Pintanel Bassets CREATIVE COMMONS)
When the Information Development team in my organization 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 our Information Development (ID) department. All of these drafts happened toward the end of a software release cycle, and were not reviewed by anyone outside the ID 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 often coincided with their busiest times of the release cycle–testing the product and fixing bugs. Because of this poor timing for the documentation review, we often got only superficial edits, or no comments at all, which didn’t help us improve the documentation quality.
In agile development, we now write documentation for a feature in the sprint (time-limited development cycle) in which it is developed and tested. For additional information about agile concepts, see Fiona Hanington’s article, Can I Be an Agile Technical Communicator When My Team Is Not?. 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. This idea is similar to daily rushes in filmmaking – use it to do a quick gut check to see if everything looks okay, or if something needs to be redone. We still send out approval drafts for some projects, but for most reviewers, at that point it is simply a director’s cut, or a chance for them to see the book in its entirety.
Spreading the Workload throughout the Release Cycle
With a traditional development environment, most documentation work is left to the end of the release cycle. Writers typically have to wait until a Feature Complete date to ensure the features are stable enough to document without a lot of rework. This method pushes most of the writer’s work into a frantic time period smashed in at the end of the cycle, when the writer may also be writing release notes, tracking fixes, and preparing for the actual product shipment.
Working in an agile environment lets writers spread their workloads through the entire release cycle. In each sprint, a feature will be coded, tested, and documented as part of one or more user stories in that sprint. At the end of a sprint, writers will have completed documentation for a number of features and can move on to other work in following sprints. Working on bits of the documentation throughout the release cycle frees up time toward the end of the cycle for consolidating final documentation, converting to help, and other doc-only work.
Conclusion
While agile development doesn’t completely erase the challenges that today’s technical communicators face, it significantly improves processes in ways that directly impact writers’ schedules, deliverable quality, and peace of mind.
References/Useful links
- Fiona Hanington, Can I Be an Agile Technical Communicator When My Team Is Not?, TechWhirl, may 2013
- Succeeding with Agile – Mike Cohn’s blog (http://www.mountaingoatsoftware.com/blog/)
- Agile Testing with Lisa Crispin blog (http://lisacrispin.com/)
- Essential Scrum: A Practical Guide to the Most Popular Agile Process, Kenny Rubin (http://www.amazon.com/Essential-Scrum-Practical-Addison-Wesley-Signature/dp/0137043295/ref=sr_1_1?ie=UTF8&qid=1380477712&sr=8-1&keywords=kenneth+rubin)
- Mobile and Agile: The Floating Writer’s Survival Kit, Alyssa Fox and Meredith Kramer (http://www.writersua.com/articles/AGILE/)
