The following article was produced for and published in the ASTC Southern Communicator, Feb 2012
This is the first of a two-part article on documenting in an agile software development environment. Part 2 is here.
Part 1 focuses on the background by describing what agile is and how it affects us as writers, including the key problems and benefits.
What is agile and how is it different from traditional methods?
Agile is a software development methodology that encourages collaboration and flexibility. There are in fact a number of different agile methodologies, each with their own terminology and activities, but between them they have common practices and goals. The major aim of agile is to produce and ship useful, working software as early as possible to customers, while attempting to avoid some problems seen in more traditional development methods.
Traditional software development methods, such as the waterfall model, define a strict process for development, where each stage of development is completed before the next stage starts. Typically, in these projects, the entire plan for the project is defined at the outset. When the requirements gathering stage is completed, the requirements are locked, and work proceeds into the design phase to produce a detailed specification based on these requirements. When the design specification is completed, the work proceeds into the development phase, and so on. At each stage detailed supporting documentation is produced.
This large initial design effort relies on the requirements being correct and feasible, but in reality:
- Requirements often change
- Technical feasibility or usability of a design may not be known until development has actually started
- Code to test these assumptions may not be available for many months
- Integration activities come late in the cycle and may mean that problems are found at a point where they are expensive to fix
- Development cycles may be very long, from months to years
- Original requirements become out of date, and that means the product needs to dramatically change in order to still have value for the client.
All these problems can mean that the development team has to go back and alter the requirements or the design to accommodate the unforeseen changes. This can be costly, and may mean a lot of wasted effort or activities need repeating.
Traditional software development processes may be disconnected from the users of the software. The user may be involved with requirements gathering, but left out during the planning of product implementation. Consequently, the user might not see the product until a late stage in its development cycle. This same disconnect may also take place between traditional roles, which may change throughout the project. Project roles in one stage may have no knowledge or influence over the activities of other stages. For example, the developers, testers, and technical authors may have no knowledge of the user requirements, or involvement in the specification phase of the project.
Agile development methodologies take a different approach. The same stages are still used, but rather than plan the requirements and design for a whole project, the project is split into shorter periods called sprints. Within each sprint, the design and development of just a few high value items is planned and carried out.
Other differences from traditional approaches are that:
- Development cycles are shorter
- Less code is written, so fewer bugs are introduced
- Problems are found earlier
- Function is delivered to the customer sooner
- Software is delivered early, frequently, and continuously
- Customers can receive a feature as soon as it is developed and tested.
Compared to traditional methods where there may be a frantic drive at the end of the project to complete on time, agile 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.
Agile development also embraces changing requirements. Customer collaboration and stakeholder contribution is very important in agile, and regular involvement by customers and stakeholders is encouraged. Because of the frequent release of software and the involvement of stakeholders, more feedback is received and accepted from customers, and as a result more changes to requirements can be expected. Although there may be a high-level plan providing a strategic direction for the long term, these plans are not detailed.
Detailed planning happens only for the short term, often only for the current and next sprint. The result is that it is very easy to change plans as development goes on. If something is urgent then everything can stop and the sprint be re-planned, or more commonly the plan for the next sprint is altered.
Rather than spend time creating detailed support documentation, agile relies instead upon verbal communication and collaboration with team members and customers. This has the advantage that everyone in the team knows the status of the project, so plans and requirements can be changed with minimum effort. It is more valuable to get on with designing and developing working software than it is to spend your time writing about how you are going to do it.
Agile methods also change the way that the development teams work. Agile teams are:
- self-directing. 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
- multidisciplinary with all the different disciplines required to develop and test the software and supporting documentation including programmers, testers, technical communicators, and ideally usability practitioners.
What does agile development mean for writers?
Agile development can be a very different way of working for many writers. This change can be scary for some, especially as the writing teams or individual writer are often 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.
In fact, if agile is being done properly in a project, it can be a better and more enjoyable way of working.
Even if your organisation doesn’t use or isn’t considering using agile development, there are techniques and behaviours in agile that are beneficial for writers, including ways of planning the user documentation, getting information about users and the design, and ways of working with the development teams to get effective feedback on the documentation.
The most obvious change for writers is the change to iterative development, which takes place in a series of repeated cycles called iterations or sprints. These cycles contain design, development, testing and documentation and can last between two weeks and two months, depending on the size (and history) of the project.
These sprints can have a significant impact on what gets written and when. Within a sprint, the focus is on producing some function that is useful to the customer. In each sprint, priority is given to developing task-based user documentation that helps the customer use the software function currently being developed. User documentation, such as concept guides and reference information might have to be written later in the sprint or possibly even in a different sprint. The user documentation might also need to be written before the code is developed. Development, testing, and writing activities can happen in parallel in agile development.
A sprint is only complete when all of the activities that are needed to create software that is ready to ship to the customer have been finished. These activities include completing all the code, testing, user documentation, and fixing all the problems. This means that the documentation also has to be written with time remaining for testing, receiving feedback, and fixing problems before the end of the sprint.
Design does still happen in agile during each sprint, but communication of the intent and behaviour of the software and associated user documentation may be provided by face-to-face communication, rather than through the use of detailed, formal design specifications and plans. If you are used to writing from design specifications this change may be a shock, but there are other ways to get the information you need. There is less reliance on detailed design specifications and technical documentation for communication. Instead, depending on the size of teams and the locations of team members, there is more reliance on other types of design documentation including:
- Content storage systems, such as wikis, that enable content to be captured quickly and cheaply and are rapid to update, may be used effectively to store these less formal design documents
- Prototypes are often available early because coding usually happens more quickly in agile. They demonstrate how the software looks and will work for the user.
Maximising work not done
A principle of agile is ‘maximising work not done’. This means understanding what the user really needs and producing this function as the priority. If a user doesn’t want or need a function, don’t bother developing it. This means that the software is leaner and more usable to the customer. The developer should implement a function because the user needs it, rather than because the function is cool or clever.
This principle of maximising work not done applies to the user documentation in the same way as it does to code. If the user doesn’t need it, don’t write it! As writers we like to provide everything our users might possibly want in every available format. In agile this is the wrong approach to take – you should not duplicate content in different forms, but instead provide what the user needs in the most appropriate format. For example:
- A tutorial. 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 the tutorial and an extensive library of documentation covering the same topic
- Embedded assistance. Rather than providing user documentation about the interface, it may be better to integrate it into the interface.
You don’t have time to write everything and produce everything in multiple ways, so, based on user needs, prioritise what you write and how you deliver it.
A major principle of agile is to accept and embrace changing requirements that come as a result of user’s changing needs or their feedback on software delivered. 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 alongside 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 is a leaner and more useful product for the users. This can mean that more time is 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 sprints. Rather than being given detailed design specifications to work from, the team comes up with their own designs and decide themselves how to work together to solve the technical problems.
Teams are multidisciplinary, which means that the teams contain developers, testers, writers, and others such as service and usability personnel. Staff may also be expected to change roles as needed by the team, for example a writer may be asked to do some 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 sprint.
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.
Agile has a strong focus on working with the users or stakeholders representing the users. The early and regular release of software provides writers with opportunities to get feedback on the user documentation from both users and stakeholders on the project, as well as from other members of the team.
What are the key problems for writers in agile?
Many of the problems of agile development are not actually a problem with agile development itself, but rather the way individual teams choose to implement agile.
A common problem for writers in agile is not being included as part of the agile team. The developers go ahead and develop the software without including the writers. In this case, the writers have to wait until the software is complete before they can write documentation, but have no design specifications and only the working software to work from. This is extremely ineffective and is not agile being done correctly. The documentation is essential for the users, and the writers must be a part of the agile development team, developing the user documentation concurrently with the software.
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, for example where team members are remote or even in different time zones. Efforts should be made to include remote members of the teams in meetings, but there are other communication methods that can be effective for sharing information and discussions such as recordings, emails, wikis, web conferences, and instant messaging.
Correctly setting the size of work items within each sprint is extremely important in agile – failing to do this is probably the most important factor in getting agile wrong. Because sprints tend to be a set size for a project, there is a temptation to keep the sprints the same size and squeeze functions of all sizes into this sprint length, regardless of how long it actually is. The desire to ‘embrace changing requirements’ can also mean that management want to squeeze in something new part-way through a sprint. Trying to add too much or extra to a complete plan will ultimately cause the sprint to overrun. The best approach is to take items out of the sprint if it’s necessary to add something new – unless the sprint is making better progress than expected.
Extensive rework can be a common problem for writers in an agile project, although this is more likely to be a problem where the development team is not doing agile properly. Because the planning is not long term and changing requirements are taken on, there is the potential that a function developed in this sprint is changed substantially or thrown away in the next sprint. In a proper agile project, however, this is less likely to happen. The function that is developed in this sprint is completed, and unlikely to be revisited because the agile team will move onto new function in the next sprint. If the documentation is being created concurrently, no rework is required. Some rework can occur when the code is changed because of user feedback, but the earlier the feedback is received, the less rework will be needed in the long term.
What are the key benefits for writers in agile?
Probably the most rewarding experience in agile for writers is working in an agile team. Agile provides an opportunity for writers to influence the development teams and to improve the way they work with them. As a member of the agile development team, the writers tend to be viewed much more as key contributors than on non-agile development projects.
For many writers, agile provides an opportunity to get actively involved with the design process, and even provide more visibility for the design and requirements of the user documentation. Design typically involves the whole agile team and stakeholders. This provides the opportunity for writers to understand the user requirements and design decisions for the features being developed.
Writers often have a good understanding of the needs of the users, and can make a valuable contribution to design discussions.
The user documentation can itself become the central point for communicating the external design of the software, by providing details of how the software looks to the users and how they will interact with it.