Reply to comment

Agile is a set of software development methods aimed at speeding up software development process and making sure the software meets the needs of user. Scrum in a slimline project management method that is frequently used in Agile projects. How do they work with the need to produce high-quality user documentation?

 The use of Scrum and other Agile methods is growing quickly in software development projects. Scrum can be applied to a variety of different projects, including software and hardware projects, and documentation projects. Agile and Scrum are increasingly popular because they fit together so well and they genuinely seem to work. Research finds that Agile-Scrum teams are generally more productive than traditional software development teams. They deliver higher-quality software on a more regular basis.

A problem for user documentation

Agile and Scrum both cause problems for user documentation. Agile prioritizes the delivery of working product over the preparation of traditional written design artefacts like the use cases, interface sketches, QOS data, wiring diagrams, and parameter lists that are essential grist to the technical writer's mill.

Scrum organizes developers (the "pigs") into tightly knit teams who communicate daily with one another on a face-to-face basis. Communication with non-team members (the "chickens")  tends to be limited. Indeed, one of the Scrum roles is tasked with shielding the team members from outside distractions - like, for example, technical writers jumping up and down outside the team room door trying to get information.

(Some developers may say that this is an exaggeration - that their door is always open to sensible enquirers, even writers - but experience shows that even the friendliest of teams hunker down as deadline days approaches, and those previously wide-open doors remain firmly shut.)

The lack of documention coming out of Agile teams and the exclusivity of Scrum teams makes it hard for technical writers to do their job if they are outside the project team. Most companies using Agile and Scrum have found that separating documentation from development just doesn't work.

The only way to deliver good end-user documentation under Agile and Scrum is to put at least one writer in the team, working side-by-side with the other people building the product. In that way, writers become less reliant on formal specifications like use cases. I've been fortunate to experience first-hand how Scrum, Agile and user documentation can be put together in an effective software development process: my client MoSync AB in Stockholm have implemented just such a process to ensure the fastest and most efficient development process for their cross-platform mobile SDK. The technical writer sits at the heart of the development team, interacting on a daily basis with all the team members -- developers and testers -- and taking part in all the team meetings.

Most teams are surprised just how much help a good writer is to the team, not just as someone who can write user manuals, create help systems, or fetch the coffee, but also as someone who can check user interface strings, coordinate translations, create publicity materials, and to help out with those endless boring PowerPoint presentations proportedly showing progress.

(But of course the composition of the Scrum team reflects the nature of the product being delivered. If the product is purely internal and no user documentation is required, there is probably no need to have a writer in the team.)

Testing documentation

Agile says that “user documentation is as much a part of the product as source code”. If a product has user documentation associated with it – an installation instruction, a wiring diagram, a command reference that aids the use of the product and its features – that documentation must be considered to be an integral part of the product itself, and must be delivered at the same time as the software and hardware components of the product.

User documentation in Agile is should always be tested together with the other parts of the product. System testers test the product by following test specifications based on the product's original requirements (user stories, use cases, quality-of-service statements) and the test specifications should include tests for all parts of the product including user documentation. To give an example, if the product is a hardware board, the installation instruction for the board should be tested with the board and its socket, and the test specification should state clearly that's how testing should be carried out.

Putting writers in the R&D development teams makes sure that user documentation is delivered alongside the other product components, and that the documentation is seen by all participants as an essential part of the product, not something to be tackled later when the team can get round to it.

Alternative Scenario

But suppose a decision is made not to include a writer in the development team? What then?

Having a writer in the development team is not always feasible, particularly in cases when the R&D Department is completely separate fiefdom from the Documentation Department. In such circumstances, the following approach is recommended:

• First, make it clear to the development team that their sprint deliveries are incomplete (according to Agile) until the user documentation for the delivery has been written and tested. (This is necessary to make sure that the team understands its obligations under Agile.)
• Then agree to delay delivery of the user documentation by one sprint cycle. That is, the documentation for the product or features developed in sprint n will be written and tested in sprint n+1. (This formalizes the lag that will be caused by separation of developers from writers. We are basically saying to the developers "If we are not going to be part of your team, then we will only act after your deliveries.)
• And agree that, for each sprint, the development team must deliver a complete set of updated use cases and all the supporting data items (for example, configuration tables, screen shots, clean room data, parameter lists, etc.,) that are required to write the user documentation for product or features they are delivering in the sprint. (This defines the deliveries expected from the development team to the documenters.)

The point I'm making here is that if there isn't a writer in the Scrum team, you need to very clearly establish the what the development team will deliver, when it will deliver it, and when the writers will act on it.

It should be obvious that the alternative approach delays not only the documentation, but also delays the documentation testing, and therefore delays system testing. And it should also be apparent that this alternative approach requires the developers to prepare the deliveries that the technical writers will need and which thus puts more work on the R&D Department.