The following article was produced for and published in the ASTC Southern Communicator, June 2012
This is the second of a two-part article on documenting in an agile software development environment. Part 1 is here.
Part 2 focuses on the more practical considerations, such as the role of the documentation manager, how to plan your documentation, find the information you need, obtain feedback and perform usability testing.
What is the role of the documentation manager in agile development?
The documentation manager has an important role in agile development, not least because they need to agree on the move to agile in the first place and ensure that the writing team is provided with adequate education. Ideally education on agile development should include all the members of the agile team.
The documentation manager must also work with the other designers and project managers to understand roles and responsibilities whilst using agile development. In order for agile to work effectively for the writing team, the writers must be part of the agile teams. The manager has the responsibility to make sure that the writing team is fully involved in the agile process if it is adopted.
The majority of user documentation management in an agile project is very similar to a non-agile project. This includes resourcing, costing, planning, prioritising, and ensuring effective communication between development and the writing team. An important aspect of the management role in agile that might be different is a need for the manager look at the big picture. A downside of agile is that it becomes focused on features, and work items that don’t relate directly to code being written in the sprint tend to get overlooked or problematic to include. Examples of non-feature related work include items such as installation, migration, troubleshooting, high-level concepts, and reference information. Planning must include these non-feature related work items with dedicated time included in the schedules. They can be included in the work for the normal sprints, completed in in quieter sprints, or perhaps given to a team working outside of the iterative process. Other tasks that might need to be planned for are quality work, for example, information architecture, migration to new tools, and maintenance of previous releases.
The documentation manager should also be involved in ensuring that the agile teams are working in an effective manner. The documentation manager should encourage the members of the documentation team to report any difficulties promptly, and seek assistance in solving them if required, either through the status meetings or directly to the sprint manager. An important principle in agile is regular reflection by teams on how to make themselves more effective, and then adjust their behaviour accordingly. The documentation manager should help facilitate lessons-learned activities at the end of each sprint, where teams should discuss the successes and failures of the previous sprint.
Planning in agile
The majority of planning in agile development is planning the content for individual sprints. Usually the current and next sprints have detailed planning, whilst other future sprints are not planned in detail.
Because the software and documentation should be complete and ready for release at the end of each sprint, the documentation must be prioritised based on the importance for the user.
Sizing for documentation is based on experience, and should be refined throughout the project. A useful strategy for sizing documentation tasks is to identify the topics or information units that need to be created or changed in the next sprint and calculate an approximate size for each task. Depending on the sprint, the technical writer should break down large tasks into smaller tasks. Tasks that are sized above three to five days may be difficult to adequately estimate in a sprint, and may result in slippage if the task cannot be completed in the sprint. For short sprints, for example, one or two weeks, tasks sized at over one day should be broken down into smaller tasks for the purpose of sizing. The sizing also needs to include time for reviews, testing and fixing problems. If the sizing does not fit in the sprint, put what you will do in this sprint in the plan, and schedule what is left for the next sprint. If the sizing seems too big then you need to prioritise. What does the user really need? Do they need it all? Can you provide it in a different way?
The sprint cannot end without the documentation approved as complete, or without arrangements being made to carry over unfinished items. User documentation in draft form has to be ready with enough time for review and for edits to be made.
In a traditional project that requires translation or localisation, this is typically done at the end of the project – when the documentation is ‘complete’.
In agile, because the software and documentation could potentially be released to the users after any given sprint, leaving translation and localisation to the end of the project may not be practical. It is probably impossible for translation and localisation to be completed in the same sprint in which the documentation was written because of time constraints. How often and when you choose to do the translation and localisation depends on whether translated or localised versions need to be released at the same time as the software. An advantage of completing these activities more often in the cycle is that the length of time they take is reduced, because the translation and localisation is performed on smaller quantities of documentation on each occasion.
When planning translation and localisation, calculate how much time you need for the activities including packaging, translating, handling returns, testing and integrating. If you need to complete all of the activities in each sprint, prioritise the material to translate or localise based on local requirements, regulations, and the needs of the users. Alternatively, if you don’t need to do all the activities in a single sprint, consider translating or localising documentation in one sprint, and then incorporating the returned documentation in the next sprint.
Finally, a useful strategy to make it more practical to fit everything into agile is to use consolidation sprints. These are sprints when development of new code is low, or more focused on code that is not visible to the users. For developers not involved in coding, these sprints can be used for translation of interfaces and messages, integration of different parts of the software, user acceptance testing, and so on. For the writers, these sprints can be useful for some of the non-feature related items, such as user guides, concepts and references materials, integration, usability testing, and translation.
Getting the information you need in agile
In agile development, the primary method of communicating design decisions is by face-to-face communication, rather than through the use of detailed design specifications. This may mean that you may use other techniques need to be used to get information that you need to develop the user documentation, many of which you may already use.
Despite the lack of detailed design specifications, there are some useful documents that should be produced in agile development that help developers, testers, and writers to understand what is being developed for the users, and also importantly, why. These include:
▪ User roles
▪ User stories
▪ Use cases.
It is important in any project to understand the users that are the target audience for the software and the documentation. For any given product there is likely to be one or more user roles that will use that product for example:
▪ Web developer
▪ Systems administrator
▪ Technical support officer
▪ Lab assistant.
Each user role will have particular tasks they perform or goals that they want to achieve. They may also have a set of associated skills, and they may work in a particular environment.
Personas are an extension of user roles where you create a fictional character that represents a group of your users. A persona typically includes the following types of information about the fictional user:
▪ Name, age, education, experience
▪ Job title, responsibilities, skills
▪ Goals, tasks, business needs
Physical and social environment
A story is used to detail what a user wants to do with your product, or a part of your product. It describes just what the goals and tasks are, and not how a particular user might use the product.
Scenarios extend stories by using a specific user, for example based on a persona, to detail specific requirements that the user may have, or a specific way that this user uses your product, based on their existing knowledge and experience or particular environment. A story tends to focus on the so-called ‘golden path’. A user wants to achieve a particular goal, and the steps for them to do that are likely to be considered. In the scenario, problems with the golden path may be highlighted, and alternate paths may need to be explored to support users with the same requirements as the persona.
Use cases are used to describe the interaction of a user with a system (and sometimes system to system interaction). They provide the commonly expected way that a user uses a system, and what happens, but also problem conditions and alternative interactions.
You can use the information from these documents to help develop the user documentation, for example to structure the documentation for the different roles, decide on the conceptual information that each role needs based on their skills, identify the tasks and business needs to support, develop troubleshooting information based on problem conditions that can occur, and so on.
Interviewing is the most obvious technique for eliciting information directly from your developers, and is a technique that you probably already use. Another useful technique is pair-programming, where you sit down with the developer and get them to show you what they have done. As well as helping you get information for the documentation, the technique can provide the opportunity to work together, for example, by getting your input on terminology and best practices for labels in interfaces or when writing error messages.
It is quite common in agile for the software developers to use demonstations to show progress to stakeholders and get feedback. Getting involved in these meetings provides opportunities to see how the software is working. The stakeholders in the meeting will also ask questions that will result in changes to the software or that can be used to enhance the documentation.
Getting documentation feedback
It is important to ensure that the documentation you provide for your users is not only well written, but also correct and usable. There are a number of techniques for validating the documentation and getting feedback from users. The user documentation should therefore be reviewed for style and for technical accuracy, and also tested with the software for accuracy and for usability.
In agile environments, it is useful to have reviewing tools where comments can be added directly to documentation, for example where developers and testers can add comments directly onto the page. The advantages of having such a mechanism is that the context is clearer, making it easier to understand what the comment means, it is more lightweight than a formal bug tracking system, and other members of the team can easily see and contribute to the comments that have been made.
In the same way that developers can use demos to get feedback on their software, writers can also demonstrate the documentation to the agile team and other stakeholders. These walkthrough meetings can be used to review both the structure and content of the documentation. Updates can even be made during the meeting so that changes can be seen immediately to compare different options.
As well as getting input into the documentation, pair- testing is an excellent approach for testing both the documentation and software. By sitting with the tester as they test the software you can pick up steps that you may have missed, and encourage the tester to use your documentation when they use the product. Again, you can make changes live, or changes after the event.
An important testing activity for both the software and the documentation is usability testing. In usability testing you get a user or someone representing the user to use the software with the documentation. Observing this testing tells you at what point the user needs to use the documentation, whether they can find what they are looking for, and whether there are changes you can make to help them with particular problems or expectations. Usability testing is an activity that can be scheduled during consolidation sprints, but it is important to ensure that problems encountered during the sessions have time to be fixed before the software becomes available to users.
User feedback is obviously valuable for improving the user documentation and also understanding the needs of customers. User feedback can come from customers using released versions of the software and the documentation, from stakeholders representing the users, and from the other members of the agile team.
In summary then, the term ‘agile development’ relates to a number of different software development methods that share the same principles of flexibility and collaborative working. An agile development project creates functions of value to customers in short cycles known as sprints or iterations. Each sprint includes all the activities required to ship the function, including coding, testing, and documenting. Once a sprint is completed, the team moves on to develop the next function, leading to early, frequent, and continuous delivery of software to the customers.
An agile team is multidisciplinary and is responsible for how they work together, and how they solve their own technical challenges. Agile development teams include customers, or stakeholders that represent them. The teams embrace changing requirements based on user feedback or changing user needs. These changes to requirements can be accommodated because detailed planning and sizing is only carried out for the short term.
There are a number of benefits of agile development for both our customers and for us as technical communicators working with development teams. Our customers get useful functions more quickly and have the opportunity to shape the products under development through regular contact with the teams. The benefits for us are a closer, more collaborative, relationship with our developers and testers. Instead of communicating through documents, we communicate face to face, or as close to that as we can! Most importantly we are a part of the same team, rather than a separate support team and therefore we are equal in deciding how the team should work together. Agile development provides the opportunity to be actively involved in the design of products from the beginning and have more contact with customers and project stakeholders.
Adopting agile development is not like waving a magic wand. Agile development requires learning and a willingness to try things out. For it to be successful it is important that all members of the team, in particular the project manager, understand what it means to use the method properly. A team that simply calls itself ‘agile’, or just does ‘the good bits’ is not doing agile development. Every team member must be involved; agile development is not something just for the software developers!
The International Standard, ISO/IEC 26515 Developing user documentation in an agile environment, is a useful guide to the best practices, roles, responsibilities, and activities required in agile development. The standard can be used by project managers, documentation managers, technical communicators, and related roles as a set of valuable guidelines for understanding and applying the method effectively.