Developing user documentation in an agile environment: An International Standard

UPDATE: The standard is now available: http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=43074

This week I gave a presentation with this title to the Technical Communication UK 2011 Conference. I’ve attached the slides that I used in the conference here: TCUK11_Agile, although they won’t really mean much to anyone! The majority of the presentations I’ve done in the past do rely on Power Point (spit spit) and an excess of text. Given that neither standards or agile are an exciting subject, there was a very large chance the presentation would be all text and very dull! So I wanted to use lots of pictures, but still make sure that I could remember what I wanted to say. So.. because they won’t make any sense on their own, here is a write-up of what I said (or at least intended to say)!

First I’ll start with a little of my background and why I was doing a presentation on this subject. I wear a number of different hats, and for this presentation I was wearing my ‘documentation standards’ hat. I have the privilege of being the UK Principal Expert for the BSI for standards on documentation in software and systems, and part of an ISO working group (ISO/IEC JTC1/SC7/WG2). In this role I’m editor for international standards, previously one on testing and reviewing user documentation, and the one that I will talk about in this presentation on developing user documentation in an agile environment. (The work we do on the standards is all voluntary btw).  No-one sensible calls themselves an expert in agile development, but I have been working with more or less successful teams using agile development within IBM for about 3 years.

The presentation itself covers a little bit about standards and what we do in the working group, a brief introduction to agile development, what agile development means to writers, and then finally some of the guidance and requirements from the standard.

Firstly, I’ll explain this acronym:  ISO/IEC JTC1/SC7/WG2. This acronym explains where our working group fits into the food chain of International Standards development.

Breaking the acronym down, ISO/IEC JTC1 is broken down into the following parts. ISO is the International Standards Organisation and IEC is the International Electrotechnical Commission. The  JTC1 means Joint Technical Committee. So this part means that we’re part of a joint technical committee of the ISO and IEC. This committee is responsible for producing International Standards for Information Technology. SC7 is one of several sub-committees, and sub-comittee 7 is responsible for developing standards for software and systems engineering. Finally WG 2 is one of a number of working groups underneath the sub-comittee. Working group 2 is responsible for producing standards for documentation in software and systems engineering.

So what is a standard? A standard is a set of mandatory requirements established by consensus and maintained by a recognized body to prescribe a disciplined uniform approach or specify a product, that is, mandatory conventions and practices. This is a good thing for the production of products because they work together in a safe way (see the photo on slide 6 of what happens when there is no standard!) and is good for business. If an organisation complies with a standard then you can be sure they are following best practices, and potentially work more effectively with them. The ISO standards are developed by negotiation and consensus with experts around the world, meaning that they are appropriate for universal and worldwide use. The standards are developing iteratively, with drafts created by the working groups by consensus, and then sent out for ballot and review by national standards organisations, presenting the standards to a larger body of experts and organisational representatives.

Working group 2 develops standards relating to both documentation in the life-cycle and user documentation for software and systems. For user documentation we have a suite of standards that are aimed at different user roles involved with developing user documentation including authors, designers, managers, reviewers, testers, acquirers, and suppliers. The standard on developing user documentation in an agile environment is part of this suite of standards, but is designed to supplement the existing standards by providing activities and behaviours that are applicable specifically to an agile environment.

So why did we decide to do a standard on agile? Well, firstly as suggested above, agile development can certainly be quite a different way of working for teams used to more traditional methods. Agile is being increasingly adopted by organisations, but the existing guidance on agile is very developer focussed. There isn’t very much out there for writers and user documentation developers. We felt the community would benefit from the guidance the standard could provide, but also by adhering to the requirements in the standard would promote best practices and help writing teams make agile effective in their own organisations.

As writers we may not be able to change the way the developers work, but we can influence and improve the way we work with them!

So what is agile all about? You may have heard lots of different terminology to describe agile, and their are different methodologies with their own terminology and activities. There are however some common terms and practices that this presentation, and the standard, focus upon. The truth is also that organisations doing agile all seem to be doing something different! Contrary to myth (and the cartoon on slide 9) agile is not all about abandoning planning, chucking away all the documentation, and throwing together some rubbish code. This approach is known as cowboy programming!

The major aim of agile is to produce and ship useful, working software as early as possible to customers, whilst avoiding some problems of more traditional software methods. <aside>I can’t (with this particular hat on) make statements about whether agile is better or not than other methods. Have a look on the web for the background and comparisons, especially http://agilemanifesto.org/). Check back in November when I’ll be wearing a different hat 😉 </aside> Agile methods have two main areas of impact, how the software is developed and delivered, and how the teams work.

Software is delivered early, frequently, and continuously. What this means is that as soon as a feature, that is useful to the user, has been developed and tested, it is delivered to the customers. Then the next function is delivered and shipped, and so on continuously. The idea is that this method of development and delivery is sustainable. Working software is the measure of progress in agile. When something works and is useful, it is ready to be shipped. But if it does not work, the team cannot move on until it is fixed. These cycles of development and delivery are known as sprints or iterations. Agile development also embraces changing requirements. Because of the frequent release of software and the involvement of stakeholders in agile, more feedback is received and excepted from customers, so more might changes come in. Agile doesn’t plan for the long term, although there may be a high level plan for the long term providing a strategic direction, these plans are not highly detailed, and detailed planning happens only for the current iteration, and perhaps the next. This means that it is very easy to change plans as development goes on. If something is urgent then everything can stop and the iteration be re-planned, or more commonly the plan for the next iteration is altered.

As mentioned, a big change that agile development often makes is the way that teams work together. Firstly is the delegation of responsibility. Agile teams are known as self-directing teams. Management may assign resource and tasks to agile teams, but the team members themselves are responsible for working out how to work together and how to solve their technical problems. Within agile customer collaboration and stakeholder contribution is recognised as being very important, and this means that everyone with an interest in the development, including users and their representatives should have regularly contact with the development team. Ideally on a daily basis. Agile asserts that face to face communication is more effective than reliance on detailed or formal life-cycle documentation. Its better to get on with the design and development and to produce working software, than spend your time writing about how you are going to do it. Agile often makes the assumption that the team members and everyone involved are in the same place and can talk face to face. This is unrealistic for many organisations, but there are other communication methods that can be effective even where workers are remote or even in different time zones. The final behaviour of an agile team is to actively seek to improve their own effectiveness and performance, and this is done through regular lessons learned activities.

So what does agile mean for writers?

Development takes place in repeated cycles called iterations or sprints. These cycles contain design, development, testing and documentation. They typically last between 2 weeks and 2 months. These sprints can have a significant impact on what gets written and when. Because what needs to be produced is user documentation that helps the user to use the feature that is developed, task information tends to be the priority in the iteration. This mean that concept guides and reference information, for example, have to come later in the iteration or possibly even a different iteration. The documentation might also need to be written before the code is developed. The documentation has to be written with time provided for testing, feedback and fixing problems before the end of the iteration.

Design still happens in agile (really!), but communication of the intent and behaviour of the user documentation may instead be provided by face to face communication, rather than through the use of detailed, formal documentation plans.  For many writers agile provides an opportunity to get involved with the design process, and even providing more visibility for the design and requirements of the user documentation. Design takes place in each iteration and should involve stakeholders representing the user.  The user documentation can itself become the central point for communicating the external design of the software, providing a source of how the software looks to the users and how they will interact with it.

There is less reliance on detailed design specifications and technical documentation for communication, and more reliance on other types of design documentation depending on the size of teams and the locations of team members. Content storage systems that enable content to be captured quickly and cheaply and are rapid to update may be effectively used to store these less formal design documents, for example wikis. Because coding usually happens quicker in agile, prototypes are often available early to demonstrate how the software looks and how the user will interact with it.

A principle of agile is “maximising work not done”.  This means deciding what the user really needs and producing this as the priority. If a user doesn’t want or need a function, don’t bother developing it. This actually means that the software is leaner and more usable to the customer. The developer shouldn’t implement a function because it is ‘cool’ but because the user needs it! This principle applies to user documentation in the same way as it does to code. If the user doesn’t need it, don’t write it!  This will often mean not duplicating content in different forms. For example, if a tutorial will be more useful and cover what is needed for the user of the new function then this will be produced alone rather than producing both this an extensive library of documentation covering the same topic. Or using embedded assistance rather than documenting the interface. You don’t have time to write everything, and write everything in multiple ways, so prioritise based on user needs!

Agile has a stronger focus on working with the users or stakeholders representing the users, and also the early and regular release of software provides writers with opportunities to get feedback on the documentation from both users and stakeholders on the project.

A major principle of agile is to accept and embrace changing requirements that come as a result of changing needs for users or feedback on software delivered to users. This means that the plans may change and work that has previously been developed may be changed or even completely removed from the products. This applies to program code and the documentation developed along side it. It can be difficult for members of the development team to discard work they may have spent a lot of time developing, but the end result a leaner and more useful product for the users. This does mean that more time may be spent on reworking the documentation than writers are used to.

Most agile projects use self-directing teams and promote development sprints, teamwork, collaboration, and process adaptability throughout the life cycle of the project.  In agile, teams are given responsibility for delivering the functionality assigned to them in the iterations. Rather than being given detailed design specifications to work from, the team comes up with their own designs and decide themselves how to solve the technical problems. Teams are multidisciplinary, which means that the teams contain developers, testers, writers, and others for example service and usability personnel. Staff may also be expected to change role as needed by the team, for example a writer may be asked to do testing, or another member of the team may be asked to help with writing depending on the requirements of the team at a particular point in the iteration.

Before moving on to give some guidance and requirements from the standard, just a quick word about how standards are used. The ISO International Standards primarily provide requirements – an organisation or project can claim conformance with a standard – meaning that they follow the best practices as laid out in the standard.  This conformance can be important in contracts between different organisations. Standards are also an excellent resource for organisations or products that don’t need to claim conformance because they contain best practices established from the experiences of diverse organisations across the world.  If an organisation wants to claim conformance, then the use of shall, should, and may in the standard indicates what you must follow and to what extent within the standard. Shall means an activity or behaviour you must adhere to exactly as specified in order to claim compliance.  Should is a recommended practice and where possible adhered to, but it might not be possible for all projects. And May is an action that is permissible within the limits of the standard, and usually is providing guidance on a way that a particular activity or behaviour could be done.

The first major section of the standard provides requirements and guidance on the management of information development in an agile environment and is aimed at managers of user documentation. The manager depends on the organisation or project and may be a team-leader, the project manager or a manager of technical communicators.

The documentation manager has an important move in agile development, not least because they need to agree the move to agile in the first place and ensure that the writing team are provided with adequate education.  They must also work with the other designers and project managers to understand roles and responsibilities whilst using agile development. Some projects may choose to not do agile for the documentation, or only part of the documentation (for example only online help and not printed help). <aside>Removing my hat just slightly, based on comments from the conference a big problem for some organisations is the writing team not being part of agile. For it to work effectively the writers need to be part of the agile team – this is good for everyone. The manager ought to make sure that the writing team are fully involved in the agile process if it is adopted. Ways to get involved are included here and especially in the standard. In  agile the writers need to stand up to development and say “We are valuable, doc is important to customers. We *must* be part of the team”. Be brave! You are valuable and have a valuable contribution to make!</aside>

Anyway, what was I saying? Ah yes, user documentation management. Most of the management of user documentation is much as it would be for any project with resourcing, costings, planning, prioritising, ensuring effective communication between development and the writing team, and so on, but an important part of the management role in agile is taking a look at the big picture. One of the downsides of agile is that it becomes very feature focussed and work items that don’t relate directly to code being written in the iteration tend to get overlooked or problematic to include. Planning in the iteration has to include these other work items, this may include items such as install, migration, and troubleshooting documentation, concepts, and reference information. These must be planned and included in the schedules, and can be completed in quieter iterations, or perhaps as work given to a team working outside of the iterative process. Other tasks that might need to be planned for are quality work (such as information architecture, migration to new tools, maintenance of previous releases, and so on).

Another important principle in agile is regular reflection by teams on how to make themselves more effective, and then adjusting their behaviour accordingly. At the end of each sprint teams should discuss the successes and failures of the previous sprint. The information development lead or project 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 manager.

Planning for the project requires planning the content for individual sprints. Documentation produced in each iteration is likely to be task orientated information to help the user use the function that has been developed in that sprint, although it may also be possible to schedule feature-related concept and reference materials within the individual sprints.

<aside>I’ve taken my hat off again.. Ignoring sizing is probably the most important factor in getting agile wrong! Because iterations tend to be a set size for a project, there is a temptation to keep the iterations the same size and squeeze function of all sizes into this iteration length, regardless of how long it actually is! The desire to ’embrace changing requirements’ can also mean that management want to add something new part way through an iteration, by squeezing it in! Be very wary of anyone who gives you ‘extended requirements’. Truly you can add stuff into an iteration if you make progress that is better than expected – but please, the only way you can add anything new in an already complete plan is to take something else out! Fight it, make them prioritise! Again, be brave!</aside>

Erm, what was I saying? Ah yes, sizing. The sizing also needs to include time for reviews, testing and fixing problems. A size should be provided by the technical writer for each task that they are responsible for in the sprint.  Depending on the sprint the technical writer should break down large tasks into smaller tasks. Tasks that are sized above 3 to 5 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, 1 or 2 weeks, tasks sized at over 1 day should be broken down into smaller tasks for the purpose of sizing. <aside> Work out what you need to do first (it can change, but it’ll give you a good idea how big the whole thing is). What tasks are there? What concepts might the user need? What reference? Do you need to update other things? Are you doing embedded assistance? What do you need to update to ship the product, datasheets perhaps? How long does it usually take to make something new, to change whats there? To get it reviewed/tested etc? Don’t go overboard with the chunking – you don’t need to count the words, but the more you can say what you need to produce, the better your sizing will be. If it doesn’t fit in the iteration, put what you will do this iteration in the plan, and schedule whats left for the next iteration. Sanity check what you have listed with someone else. If it seems too big – what does the user really need? Do they need it all? Can you provide it in a different way?</aside>

OK, so your developers don’t do detailed design specifications anymore? Well you need to get your input another way. Interviewing is an obvious technique, and you probably have to do it now anyway. Another useful technique is pair-programming, sit down with the developer and get them to show you what they have done. This is actually a good technique if they are working on interfaces where they can get your input on terminology and label names for example, or when writing error messages – you help each other! It is quite common in agile for demos to be used to show progress to stakeholders and get feedback. Get into those meetings, it not only helps you to see how the software is working, but also the kinds of questions the stakeholders are asking.

Ideally in agile the team have some of the following documents to help them understand user requirements and needs better, these can help developers, testers, and writers:

The first is to define and understand user roles. For any given product there is likely to be one or more user roles that will use that product. 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. Examples of user roles might be:

• Web developer
• Systems administrator
• Technical support officer
• Lab assistant

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:

the user’s name and information about their age, education, experience, and possibly even include a picture and more demographic details.

• the user’s job title and major responsibilities are included, and details of relevant skills, and other related product use – for example, software, hardware, platforms?
• what their goals and tasks are with using your product, what is their organisation, why do they want the product, what’s the problem/business opportunity that it solves?
• the user’s physical and social environment. Where do they work, with what facilities, how many sites, how many people, how many servers, and so on?

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 that 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. With 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 described 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.

User feedback is obviously valuable in improving the user documentation and also understanding the needs of customers. This 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.

It is as important that the user documentation is usable and correct for the user, as it is that the software works and usable for them. The user documentation should therefore be reviewed (both for style and for technical accuracy), tested with the software for accuracy and for usability. When reviewing and testing it is helpful to have reviewing tools where comments can be added directly to documentation (for example like comments on this blog) so that the context is clearer, and others can easily see comments that have been made. In the same way that software can have demos, so can user documentation, and a useful activity is to run walkthrough meetings to review structure and content  with the agile team and your stakeholders. Updates can be made during or after the meeting. Pair programming is an excellent approach for system testing, this time working with a tester when 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 activity to carry out, even if not every iteration is a usability test, where you get a user or someone representing the user to use the software with the documentation. This 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.

The sprint cannot end without the documentation approved as complete, or without arrangements 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.

Translation and localisation can be tricky to do in agile, primarily because of the time constraints. Its difficult to write and then translate or localise within the same iteration. When planning, consider whether translated or localised versions need to be released at the same time as the software, and do they need to be included for each sprint? How much time do you need  – include for packaging, translating, handling returns, testing and integrating? If you need to do everything in an iteration, then prioritise the material based on  local requirements and regulations and the needs of the users. If you are able to, consider translating in one sprint, and incorporating in the next.

Finally, a useful tactic 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 not visible to the users. For developers not involved in coding, these iterations 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 can be useful for some of the bigger picture items, such as user guides, concepts and references materials, integration, usability testing, and translation.

Yes agile can be a very different way of working, and that is scary, especially as the writing teams or individual writer often are at the mercy of decisions made by development teams. But there are benefits for individual writers, in particular the opportunity to raise their own profile, and the profile of the user documentation by working closely with the development teams, getting closer to users and influencing the design of the product itself.

A quick reminder about our standards. We’re hoping that ISO/IEC 26515 will be published next year. We’re on our final ballot. We also have a really useful set of standards for all those involved in producing user documentation. If you need some more weight with the development teams or think that the way you are working might not be ideal, or just want to know about best practice – take a look. You do have to pay for ISO standards, but if it makes your life easier its well worth it!

Check here for all the Sc7 standards that are published and being worked on. Check slide 35 for the numbers of our standards!

If you’re interested in reviewing our future standards and providing comments, please let me know your email address and I’ll pass it on to Richard (WG2 convenor).