Friday, November 26, 2010

Agile SDLC and some tips for technical writers

Technical documentation is usually written following the SDLC (software development lifecycle) model of the project. The text book DDLC (documentation development lifecycle) fits snugly into the waterfall model. However as customers have moved to a different way of doing and tracking business, they have moved to the Agile SDLC method (for various reasons). Development and testing have been able to follow the Agile method without too much of discomfort. Developing or testing only the selected features is okay as long as the bigger picture of the "Product" is understood. The dependencies of modules, code, and test cases have not really mattered much.

 
However, things are different for technical writers in the Agile world.

 
Although a lot of information is available about how documentation fits into the Agile methodology, standard approaches are not yet in place. This is because of these factors:

 
  • Each product is different and requires different levels of focus from the writers. For example, a complex security or network product might require the writer to learn technical stuff leaving little time for worrying about the approach.
  • Planning might be difficult as requirements might not be clear. Writers might still be looking for basic information about the product
  • Each and every Sprint (a cycle of usually a month that is taken up for development and testing of selected features) is different
  • Documentation approaches for GUI-based manuals contrasts with purely technical explanations (where writers concentrate on 1. how a product is built - the architecture, the workflow, the configuration, deployment, and administration and 2. the technology (high availability, replication, backup, load balancing, Replica management, logging, firewalls, hosting, data recovery, synchronization, and APIs.
  • Writers write well when they have something to say - that is plan a TOC and follow it and ask questions. Agile is about providing just enough documentation for the selected features.

 
So some of the common approaches that writers working in an Agile SDLC have used are:

 
  1. Wait till end of Sprint, see if the software GUI is available and then write. Document only what is available. Leave room for more text and planned features.
  2. Plan a TOC to get the big picture (how the document and yes the product will look like). the TOC comes from each feature in the Development or Testing Analysis sheet.
  3. Ensure that document is not PARALLEL to development. Else it will be impossible to write anything.
  4. Topic authoring - write information required for the topic - procedures, concepts, or reference. useful when you don't have any GUI to document the tasks.
  5. Some writers follow a "write once in 2 months" approach. This is a good approach too provided your project management agrees
  6. keep your source diagrams and screen captures in a safe place. You may need to edit these very often.
  7. keep content you write for concepts as technical teams might revert to what you wrote originally. For example, you might have written about database management in the product. The tech reviewer might have felt it was not what they had in mind. then a month later they would say, that it was the same thing they had decided on :)
  8. Ensure that you have a detailed review only every 3 months or so when some parts of the product is froze.
  9. During interim releases or internal betas, give a list of things that you will deliver and no more. Some modules will not have content and that's fine.
  10. if you can, maintain a Doc WIKI and ask the SMEs to collaborate and provide their comments

 
This should get you started! As you move on, there will be lot more you will learn.

No comments: