Being Agile in technical documentation – Part three

Two years ago, we wrote a number of posts, and an Adobe-sponsored whitepaper, on Agile and its effects on technical communication. This topic was picked by others, including Sarah O’Keefe and Mattias Sander, who made further suggestions. We thought it was time to revisit this topic, and expand on some of the issues raised.

In Part one, we looked at Agile and the Lean method’s principles of maximising value and minimising waste. In Part two, we looked at how we can minimise waste in the document production process. Here in Part three, we look at practical impact on writing. Agile creates a number of challenges for technical communicators, and this means they need to adapt their working methods in order to work efficiently.

Overall philosophy

From the previous posts, we can get a understanding of the underlying principles of Agile and Lean. These include establishing a rhythm of working continously on activities that add value. Don’t stop and start; don’t batch; keep measuring and checking. The challenge for technical communicators is how to fit into this pattern of work.

Measuring the value and the wastes

Lean and Agile place great emphasis on measuring the value of the work created and the production process itself. Measuring, and identifying “the value stream”, highlights the steps in the process that do not add any value: waste by overburden and waiting, waste caused by rework, waste caused by excessive checking, and so on.

Agile makes the assumption that the waste of creating content describing features or processes that are dropped before release is so great that teams should take a “document late” approach. If you measure your time, this can be tested to see if it’s true. It might be that more time is wasted by trying to work with little available time, or having to wait for input. Many development teams are surprised by how much time and money is wasted once they’ve been made aware of it.

Measuring the value to the user is much harder for technical communicators to measure. For example, you can’t tell how often someone uses a PDF manual. Often, they don’t do any measurement at all. This is a mistake. Usability testing, even if it is on a limited scale, and using people dragged off the street or from the staff canteen, can provide very useful information on what’s not adding value.

Working with sprints and kanban

It’s not always possible for technical communicators to complete their work in a two week window, so some work “a sprint behind”, starting work once a product iteration has finished. Other teams run consolidation sprints, where a sprint just focuses on outstanding tasks such as user documentation.

It partly depends on the team’s definition of “done”. Lean and Agile bring issues to the surface and should force teams to address them. If documentation is part of the definition of what needs to be done (and it should be), the team needs to ensure the documentation work is completed.

Whatever approach is taken, it’s important the task of creating user documentation is on the kanban board, so that sufficient attention and resource is given to the task.

Writing Agile-ly

Just-in-time authoring

One piece flow can also relate to topic-based authoring. Many Technical Authors already create their content in small pieces, topics, that can be used across different documents and media. Conditional build tags enable them to create filtered content, and content created with a particular audience in mind.

Some also use just-in-time publishing to assemble and generate documents or Web pages each time a users requests information. They also use user-defined variables to store static global information that can be used repeatedly in projects, making information portable and simple to update.

However, reviews of drafts are often issued in batches, and there may be a need to look at how this task can be spread more evenly.

An iterative publication of content?

If you have different types of users, you could publish content iteratively. This might mean, in a startup company, you write information for early adopters only at initial release, and update the documentation for less able users when the product is adopted by a wider audience.

Rather than a single major release, information could be published incrementally. That leads to a new challenge for technical communicators: knowing which parts to document and which to leave out.

Tools everyone can use

With Lean and Agile, issues that are forced to the surface are usually addressed by people swarming around the problem. With technical documentation, this can be difficult as Technical Authors tend to use tools that only they understand.

Ideally, you would have an authoring system that enables other team members to lend a hand, if required. You may need a system than can support content created by developers in a tool they know, such as Word or Markdown, or have a multi-user authoring tool that’s easy enough for occasional users.

Adopting one-piece flow could mean creating a flow that fits into the developers’ workflow. For example, it might mean using their tools, such as Git, to synchronise the development of documentation with the development of the product itself.

Communication and Scrums

Another challenge for technical communicators is that changes to the product are often communicated verbally at daily scrums. If the technical communicator isn’t at the scrum, their could be wasting time describing the wrong feature.

It’s not always possible to attend every meeting. Digital recorders can help. If the meeting is recorded on a digital recorder, the technical communicator could listen back to it later in the day. If they replay the recording at twice the normal speed, it can be reviewed quickly.

Managing variations in demand

Having an efficient system makes you more sensitive to variations in demand.

At Toyota, they address variations in demand in a number of ways. They keep the component suppliers informed of any changes, and they have many of the component suppliers located on site. To deal with changes with workload in technical communication, you can do similar things. You can establish protocols with technical authoring companies, such as Cherryleaf, to provide additional resource when it’s needed.

The development teams also needs to understand the impact of variations in demand. Ideally, the Technical Authors have some time to plan, and/or the variation can be smoothed out.

We need to understand variations in demands from end users. We need to be able to respond quickly to changes in customers’ needs, and have the ability to quickly reconfigure content to respond rapidly to any late changes to the delivered product’s functionality. Again, topic-based authoring and measuring can help.


Technical Authors can adapt to working with Agile teams, and they can work in an Agile way themselves. User documentation isn’t something that was addressed in the original Agile manifesto, and technical communicators need to fill in that gap.

We need to set up a rhythm and a way of working collaboratively. This means being on the kanban boards, collaborative authoring, one piece flow, working with the developers’ own workflow, considering the definition of “Done”, and measuring more than we’ve done before.

Please share your thoughts and experiences

Please use the comments box below.



Hi, this is great. Do you cover how to fit localization into the Agile world? Thanks.

Ellis Pratt

It may be possible to send through topics for translation as they are written, and rely on Translation Memory to spot content that has been translated previously. With XML and other forms of topic based authoring, you can break the work into smaller chunks. It would be tough to publish in multiple languages at the end of each sprint, so the work is going to be behind the publication of the English content.

Alan Chapman

Ellis Pratt, in article 1: ‘Being Agile in Technical Documentation’, described Agile development as “… a way of managing IT development teams and projects… an alternative to traditional project methods, which, it was felt, often lead to unsuccessful projects… The approach was also criticised because some faults might not be identified until towards the end of the project, which could make fixing them time-consuming and expensive.”

Kelly Waters’ article ‘What Is Agile? (10 Key Principles of Agile)’ makes the point that Driving Strategy Delivering More (DSDM) is “probably the original agile development method”. He qualifies this with the statement that, “In reality, though, agile is not a magic bullet for all software development issues. The real trick is to know lots of techniques from various waterfall and agile development methods, and to select a mixture of the best approaches that are most appropriate for any given situation. To do this reliably with any degree of success really requires a lot of experience and skill… Agile development does NOT equate to undocumented development…”. Absolutely right and a point all prospective Agile developers should note!

As a Technical Author, my early training was on military avionic equipment for the MOD using AvP70 and ATA100 documentation standards. These were the formally ‘accepted’ specifications and quite rigidly structured for content and format. At the time, I felt that the documentation methods and, indeed, the entire approach to project development did involve a lot of costly duplication, unnecessary detail and wasted effort. Recently, I have worked more on Agile IT projects with Lean methodology, which exist at the other end of the documentation spectrum. Having worked in both areas, I offer some personal observations from an author’s perspective:

• Use of Agile/Lean methodology – it is absolutely essential to have an experienced, technically competent project manager who is able to give good direction and can correctly judge what is important (gives value) and what is not (makes waste). Never use Agile / Lean methodology as an excuse for not adequately testing hardware or software – for any project, that is suicidal.
• Minimum Viable Documentation (MVD) – this is fine, so long as the emphasis is on ‘viable’ and NOT on ‘minimum’ (often interpreted as ‘do nothing’). I believe some types of document can never be dispensed with – e.g. an adequate Technical Specification for equipment. Without this document, the information just exists in someone’s head, your sub-contractors have only verbal guidelines (‘You never asked for that… that will cost more … nobody told me …‘ etc.), project direction becomes vague, equipment cannot be developed with confidence and the project’s chances of success are limited.
• ‘Fail Fast’ principle – this may be applicable in some areas of a project, but not all. Obviously, with software, it is better to fail-fast when compiling code rather than at Run-time so that errors and bugs can be accurately identified, corrected or removed. Also, if a design idea has proved to be a failure, it is better to move on to another one quickly than to persist in denial. The Fail Fast’ principle should never be used as a mantra to make mistakes, inexperience or bad judgement acceptable (‘Oh well, we messed that up, let’s quickly try something else eh?’).
• Plan the documentation – make a Yes / No documentation content list and agree early with the project team what is really necessary for the prospective audience; e.g. Do they need a complete application reference manual or would a series of quick-start procedures do?
• Never document too early – the project must ‘stabilize’ before you start documentation as features will change and even disappear altogether which results in wasted effort (this is especially true for application GUIs and PLC-based equipment).
• Attending Scrum meetings – Yes, but with caution. You can waste a lot of writing time when the meeting content hinges on the more technical aspects of programming which do not concern the author.
• Documentation control and traceability – it is advisable to link documentation issue codes (and dates) for User Guides / context-sensitive Help with the software release issue. This is especially true if several software versions exist out in the field. Keep an accurate, up-to-date distribution list.

The reduction of traditional documentation source material in Agile / Lean projects certainly means a different approach is called for and new methods of documentation are necessary. My experience of Agile / Lean project methodologies was, initially, quite negative. I tended to agree with Dilbert’s wry comment that Agile programming means, “no more planning and no more documentation. Just start writing code and complaining…”

I concluded that the misinterpreted and injudicious application of Agile / Lean principles to engineering projects tended to further denigrate documentation and devalue the work of a Technical Author. MVD further undermined the author and made them more reliant on people already under stress with exponentially increasing workloads as delivery deadlines drew nearer. If nothing is written down and no source material is available, you have to beg for the information from the SME’s. One positive spin-off from my initial encounter with an Agile project, however, was that I was able to add some very impressive new words to my Buzz-word Bingo card (Joke Alert!).

MVD does mean that the more traditional types of project source documentation have all but disappeared. This obviously has a knock-on effect for authors who now need more contact with designers and system engineers. This can, however, be a very positive experience. I found that, with adequate planning and constructive meetings, I became far more involved in the project design and development process. Authors should not hide away in a corner and attempt to document a project in ‘splendid isolation’. I soon discovered that a more ‘proactive’ (Bingo!) approach was necessary which included:

• Meetings with intended users / operators to decide on which types of document would serve them best
• Hand-on equipment training and use of the application.
• Meetings with design staff where test and maintenance procedures are on the agenda – It is not enough to be included just in the SCRUM meetings.
• Involvement with equipment dismantling, packaging, shipment and installation.
• Installation and configuration of the software and the planned update methods (if any).
• My attendance at Site and Factory Tests.
• Making the required documentation easily available (context-sensitive Help on the equipment and Wiki pages on the company Network).

From my involvement in the ‘nuts and bolts’ of a project, I was able to gain much valuable knowledge and provide good feedback to the design staff. In fact, in two particular projects, I was in a position to make some suggestions for modification and new features which were eventually included in the final design. This not only added value to the product, but increased efficiency and reduced wasted consumables. It also helped to dispel the myth (from all but the dullest of minds) that Technical Authors were just pen-pushers and that all documentation was an unnecessary paper chase.

I would like to conclude, however, with some cautionary words: not all ‘traditional’ project methodologies are old, out of date and in need of revision. Similarly, not all ‘young and dynamic’ approaches to project management are valid (you could substitute words such as ‘inexperienced and erratic’ here). Agile / Lean methodologies are not a panacea for ‘traditional’ project management / development techniques. As Ellis Pratt states in the opening paragraph, “Agile development is a way of managing IT development teams and projects…” That ‘way’ cannot be applied to all aspects of all engineering projects at all times.

For project managers to use the ‘Driving Strategy Delivering More’ philosophy effectively, they should first pass a project management ‘driving test’ which includes an understanding of alternative (i.e. traditional) project methodologies. Given that there are none so zealous as the newly converted, may God protect us all from ‘Agile Keenies’.

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.