Communicating Effectively with Offshore Developers
When a software development project is distributed across countries and continents, its information development team faces new hurdles as it tries to create effective, comprehensive, and accurate documentation and deliver it on time. Language barriers, time-zone differences, varying cultural norms, and the lack of personal relationships all add complexity to an already challenging process. The difficulties of coordinating the writing effort with architects, developers, quality assurance, customer support, manufacturing, and localization grow exponentially when a team is widely distributed. Success requires ingenuity, flexibility, and adherence by all to well-defined, robust processes.
A Distributed Project Team
At Sybase, one distributed software project employs this widely dispersed team:
- A project manager in Singapore
- A product manager in Massachusetts
- Three engineering managers in Singapore and one in Massachusetts
- A few dozen developers in Singapore, Beijing, Florida, Georgia, and Massachusetts
- Two dozen quality assurance personnel in Singapore and Beijing
- Customer support engineers in the US, the UK, Belgium, the Netherlands, France, and Germany
- A documentation team consisting of one writer and project leader, two half-time writers, and a manager/editor, all in Massachusetts
The information set for this product consists of 9,000 pages of documentation delivered as online Help with the product, as well as in print and as manuals on the web.
The writers for this project lack all of the usual informal means of gathering information. They cannot strike up hallway conversations, request impromptu feature demos from engineers, schedule face-to-face meetings, or listen over the wall to spontaneous design discussions. They cannot apply direct personal pressure to engineers for overdue information or simply remind them by virtue of their physical presence that writers need to be “kept in the loop”.
It’s All About Communication
On just about any project, technical writers depend upon easy access to information and a constant flow of communication. Yet, as we have seen, opportunities to gather information shrink when a team is widely distributed and writers are completely separated from developers. Our team is now almost completely dependent on regular, formal communication and well-defined processes. Full participation by the group, and the adherence of every team member to agreed processes, are crucial to everyone’s success.
Meetings need to be held without fail, with all stakeholders present, to keep a complex project on track:
- The project manager presides over weekly cross-functional meetings of the product manager, customer support, the lead writer, the documentation manager, and manufacturing. The group reviews schedules and the status of deliverables.
- Weekly engineering meetings include the project manager, engineering, and QA management. This team discusses features and design issues.
- The management team holds meetings as needed, usually during the design phase and the final weeks of the project cycle. The product and project managers, as well as the managers of engineering, QA, customer support, and documentation, all participate. Product evangelists and marketing join them as needed.
Minutes of all the cross-functional and engineering meetings, as well as schedules and project plans, are posted on a project web site for all to see.
Written specifications are crucial to the writers’ understanding of product features. After developers, writers, and QA review each spec, they join in a group review discussion. Conversations among offshore developers can be hard to hear and to follow, and especially so when enthusiastic developers are gathered in a room together thousands of miles away. When the team makes design modifications during spec review meetings, having developers update the specs is essential, though sometimes hard to accomplish.
Weekly reports delivered without fail help everyone see what features are currently under development, what progress each team is making, and where potential disconnects might occur. A summary at the top of each team’s section provides a quick overview, and personal reports from each contributor fill in the details for those who need to know them.
Holes in the communication process become painfully obvious when a team is widely distributed. The process might need to be fixed on the fly as a project progresses and redesigned during the post-project review period. For example, toward the end of the last release on this distributed project, it became clear that some stakeholders, including customer support and information development, had not had an opportunity to participate in QA’s bug review meetings. These team members had always been included when most of the team resided at one location. For this version, several team members who had important input or a need to know had been overlooked. Bug reviews by the entire team, not just QA, have been reinstituted as part of the formal process for future releases.
Useful Survival Tactics
After working with offshore development on two major versions of our sample project, we have devised a few new ways for our tech writers to gather information and keep a finger on the pulse of the project. Here are some tactics that other teams might find useful:
- Synchronize your local servers with those used by the developers. Synchronization allows writers to scan daily for updates to source-controlled specs, test plans, and source files and then check those files for differences. If you do not have a tool that allows you to do this easily, work with engineering to locate or create one.
- Request access to early and frequent builds. The sooner writers can test features under development, the better they can plan what information is needed, ask questions, begin writing, and give usability feedback.
- Scan lists of fixed bugs in announcements of each build and monitor the problem tracking system. Monitoring allows writers to identify product changes made to resolve issues, assess the impact on the information set, and learn what bugs no longer require documentation in the release bulletin.
- Monitor product newsgroups. Writers can pick up information on short-term and long-term product direction from customer requests and from the statements made by the company’s managers and partners. Such information can help writers design information more effectively and avoid unnecessary reorganization and rework on future versions.
- Enlist a local project manager to apply pressure personally to engineers. Aid of this sort can sometimes be the only effective means of extracting information from busy developers who do not respond to writers’ requests.
- Use email or instant messaging after hours to speed information exchange and get answers to the writer’s questions. Delays caused by going back and forth between writer and developer across time zones and language barriers can frustrate writers and slow their productivity.
- Request group conference calls to review specifications. Outline meeting protocols to minimize side discussions and other barriers to clear communication, and stick to them. Get management to require that engineers update functional specifications when plans change.
Useful Project Tools
- A robust bug-tracking system is essential for orderly management of offshore projects. Ensure that writers have access to it. Have writers review bug queues routinely and request clarification from QA or developers. Ask QA to create separate change requests for writers when issues require documentation solutions. This procedure gives writers a way to track separately, in their own queues, the requests that require specific action on their part. It also ensures that QA can verify the accuracy of documentation fixes on time, avoiding last-minute surprises.
- A project management web site with links to schedules, specifications, plans, and meeting minutes helps everyone on a project save time they might otherwise spend tracking down scattered bits of information. A centralized place with access for all smooths potential wrinkles in communication.
- Team discussion databases are a good tool for capturing and sharing otherwise evanescent feature and design discussions. They invite broad participation and create a historical record. They can provide a central place to announce incremental builds and to discuss and record processes, customer requests, and quality issues.
Although budgets might not allow for much individual travel, it is worth trying to have a few representatives from each major site travel occasionally to the other sites. There is no substitute for putting a name with a face. One meeting with even a single representative of an off-site group can help smooth project communications for years to come.
Whenever possible, it makes sense to take advantage of attendance at company-wide trade shows, meetings, and strategy sessions and add time for members of distributed teams to meet one another personally. If an individual needs to work long-term with a group at another site, consider having that person spend several weeks at that site to become more fully integrated into the team.
What About the Future?
Like many companies, ours has decided to tap offshore writers to fulfill growing information development needs at a lower cost. The US-based writers on our distributed team are likely to be working with writers based with the developers in Asia on the next product release.
After undergoing intensive training in the tools and processes used by the US writing group, the new writers will document maintenance releases and well-defined areas of the product as they develop technical expertise. In addition to enlisting them to help with a heavy workload and backed-up requests for expanded and improved information products, we hope to have them help developers write clear specifications, get questions resolved for the US-based writers, act as liaisons when we need information or review feedback from developers, and serve as on-site reminders that information developers are stakeholders in delivering a feature-rich, easy-to-use product.
About the Author