Building from Two Sides: Challenges of Writing Documentation Early

Building from Two Sides: Challenges of Writing Documentation Early
By Ben Minson

Have you ever set about doing something in a way that looked efficient from one side but not the other? In The High King by Lloyd Alexander, a young king tells the main character, Taran, how he set about building a seawall from the two sides in order to go twice the speed, but the two ends didn’t meet in the middle. For certain reasons, when I started setting up a low wall for a flowerbed in front of my house, I did much the same thing. But I knew that I would most likely end up almost starting over. I was right.

Similarly, in my work I have had to mimic this dual building process, and I have not reached the point where it will be apparent how well the results match up. The place where the wall must meet is a software release in multiple languages with complete documentation.

The Project’s Need for Early Writing

The first factor in the challenge is the fact that the development environment I work in follows a modified Agile process. Part of this practice involves a set of requirements that are not written in cement before development ever begins. The key stakeholder provides feedback throughout the project’s lifecycle; therefore, the requirements and the resulting product are subject to some change. In and of itself, this keeps me on my toes as I produce documentation that is to be released with the ever-changing software, but the goal is manageable.

When you add the requirement to ship multiple languages with the English version, you must factor in to the schedule the time it takes to translate the text in the application and the documentation. This pushes the documentation deadline much earlier. My task becomes much more challenging: to write help text completely against prototypes (helpfully high in fidelity) and with additional information from the business analyst.

The wider the gap between the completion of documentation and code completion, the wider the possibility of change. The farther apart you start the two ends of the wall, the greater the chances of not meeting in the middle. It seems sometimes that I’m building one end while squinting at the developers’ end, trying to keep my end aligned to the adjustments they make as the stakeholders give them directions. My dread has been the chances of having to go back and redo work; or worse, receiving translated material that also needs to be updated to match altered software.

Narrowing the Gap

Fortunately, the interaction designer on the project has been completing prototypes and reviewing them with the stakeholders far in advance; in fact, many of the prototyping for the rest of the project has been completed, and we still have two main segments of the schedule before our big release. This slow-setting cement will be helpful in writing documentation if it hardens in the near future.

Ironically, there is some measure of peace of mind that comes from this schedule. Because the main body of documentation is written so far in advance of the release, I feel ahead of schedule. And if I can complete my written work earlier than our projected date for submission to the translators, that submission can occur earlier.

But the balance must be found between submitting so early that changes are still possible and giving ourselves room to breathe when we receive the translations back. Like the possibilities my wall had, if we plan and execute carefully enough, the two parts will match up.

In many ways, this particular project has blazed new trails, and this will be one. I’ll have to keep some toes crossed while I hammer away on my keyboard because typing with fingers crossed would be sure to complicate the situation. On the other hand, if I try it that way, perhaps it will have the potential of saving the translators some work…

Ben Minson is a technical writer and trainer in the information technology arm of The Church of Jesus Christ of Latter-day Saints. He produces online help, written manuals, and training in person and over the Web. Ben holds a bachelor’s degree in English with an emphasis in Professional and Technical Writing from Utah State University. He is also a member of the international Society for Technical Communication. Ben’s blog on writing topics can be found at http://www.gryphonmountain.net.