Technical Writers

Technical Writers

The role of technical publications on an XP team is to provide early feedback about features and to create closer relationships with users. The first part of the role comes because the technical writers on the team are the first to see features, often while they are just sketches. If the writer is sitting in the room with the rest of the team he can say, "How am I going to explain that?" Maybe there is a good way to explain it and maybe there isn't. Either way, the team as a whole learns. Explaining the system in prose and pictures is an important link in the chain that creates feedback for the team.

The second part of the role is creating closer relationships with users: helping them learn about the product, listening to their feedback, and addressing confusion with further publications or new stories. The publications can take any form: tutorials, reference manuals, technical overviews, video, and audio. Writers should listen to customers, listening for the types of misunderstandings that arise when users really use the product. Weaknesses in communication are corrected with further publications. Weaknesses in the product turn into input for the planning process. You might, for example, pick stories that address a certain kind of "user error" based on users' criticisms.

The challenge of doing technical publications with XP comes from the pace of change of an XP-developed system. Back in the old days, you would freeze the specification early in development. The writers would turn it into manuals while the programmers turned it into code. In the XP world, the whole precise specification isn't frozen until very late in the game. The better the team, the later it is willing to make big changes. This leaves technical publications always playing catch-up.

You can get close, though. This week's stories can become next week's documentation tasks, putting the completion of the documentation one week behind the completion of the stories. Once you master that, you can try to have the documentation done the same week as the stories.

What would be the perfect documentation? It would be done exactly when the features it documents are done. It would be trivial to update when it was found in need of improvement. It would be cheap. It wouldn't add any time to the basic development cycle. It would be valuable to the users. The writing of it would be valuable to the team.

The XP philosophy is to start where you are now and move towards the ideal. From where you are now, could you improve a little bit? If you are using paper manuals that add six weeks to the deployment cycle, could you go fully electronic? Could you send out paper manuals six weeks after deployment? If you already have fully electronic documentation but it's not done until two months after the features, can you figure out a way to shift the time you spend so it's done two weeks after? The same week?

XP teams should get feedback from actual usage. If the manuals are online at your site, then you can monitor usage. If users never look at a certain kind of documentation, stop writing it. You can find better ways to invest that time. If the documentation is deployed with the product and the product has usage tracking built in, ask to have documentation usage added to the tracking. This will help you provide more of what your customers value.

     Python   SQL   Java   php   Perl 
     game development   web development   internet   *nix   graphics   hardware 
     telecommunications   C++ 
     Flash   Active Directory   Windows