Month: November 2013

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 in recognizing and learning to rise to the challenges common to most development teams.

This three-part series discusses those challenges, and shows why agile can be the better approach for technical communicators.

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, and 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. You have an obligation to provide that feedback to the developer who's coding it.

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 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 in to you producing higher-quality content that provides information that users really want.

Next time, we'll discuss how agile helps you get more thorough and timely reviews of your documentation from the team.

Note: This article was originally published earlier this year on the TechWhirl site.