One of the strategies in the Agile methodology is to create documentation as late as possible. Is this actually a good idea?
According to Scott Ambler:
A common agile practice is to defer the creation of all deliverable documentation as late as possible, creating them just before you need to actually deliver them…Fundamentally, this strategy is to wait until the information has stabilized before you capture it in documentation.
The reason for this harks back to one of the “three wastes” of the Toyota Production System – the waste of muda. The goal is to eliminate the time spent on activities the customer will never receive or would be willing to pay for.
However, there may be situations where documenting late results in one or both of the two other forms of waste – muri and mura. Muri means overburden – overloading or making things too difficult for certain teams within the production process (and/or for the customer). Mura means unevenness – which can lead to unnecessary waiting time for certain teams within the production process (and/or, again, for the customer).
If the cost of these wastes is greater than the waste of documenting sections that are abandoned at a later stage, then it may make sense to abandon the idea of “document late”. In order to be able to make this judgement, it is essential Technical Authors measure both the value of the documentation (e.g. the productivity of the user, the number of support calls, the number of times it is used) and the cost of producing it. With this data, Technical Authors can then make a stronger case for modifying this practice within Agile projects.
I think the key word here is flexibility. That said, it does depend on how much you are writing and chucking away, and that has to be balanced with how much time authors have to write docs and get them out on time.
What I find is that I can read all the background material that’s a available, then write the basics, plus add loads of notes and queries, talk to development and testing, find the graphics and pages that need updating, related info etc. By doing this, I am as prepared as I possibly can be for that bit of work. If I didn’t do that, then I’d be doing everything all at the last moment – and that’s not a sensible way to work. Especially if it leads to documentation going out that has to be rectified later. This is not only time-consuming, who wants to release faulty docs?
Authors shouldn’t be put under undue pressure time and again, but we all have to recognise that working for a software house means having to be flexible because thing scan change rapidly – it comes with the territory. Cheers.
The scrum meetings give a great opportunity for technical authors and information architects to learn about and understand the product. They can also provide valuable feedback during the design phase. Having to make a few last minute changes is a small price to pay for these advantages, in my experience.
If all the documentation is produced at the last minute – it looks like it. Typically it explains the obvious and is silent on what you really want to know.
Agile, fundamentally, is a method that recognizes the value of the learning that happens over the course of the project development. Rather than assuming that everything is known and planned for before development begins, Agile recognizes that new information will emerge in the course of development, and organized the development process first to promote leaning as much as possible and as early as possible, and second to accommodate the changes that necessarily flow from learning into the development process as smoothly as possible.
As anyone who has been involved with documentation for very long knows, an enormous amount of information about the usability, efficacy, and completeness of a design arises from the act of documenting it. The documentation process generates a huge amount of valuable information, not merely for the writers, but also for the developers.
If we recognize that the documentation effort is a central and valuable part of the agile information generating process, then agile principles clearly suggest that we should document as early as possible, and be willing to revise the documentation throughout the development process. The value of the learning produced by doing this greatly outweighs the cost of the revision — and that is before we even get to considering the value of avoiding muri and mura which is, as you say, substantial.
Spot on. Tech writers get in trouble with Agile when the project leadership (or client) says “Oh, you’re just writing the documents – go do something else until the big kids are done building it.” Sometimes that’s just laziness (not wanting to engage the TW) or reluctance (TW is too tentative to insert self), and sometimes it’s blatant cost cutting.
The problem is you lose out on that hallmark benefit of Agile, which is the learning that occurs throughout the process. I insist at my organization that all projects include the TW as early as logistically possible – not sitting in constant meetings, but at minimum a SCRUM style meeting once a week and established interactions with the team.
A factor that feeds in to this is the issue of what you document. There’s a good chance that the externals of the system, and the user interaction, are defined relatively early while the internal implementation on various platforms takes longer. Assuming you’re documenting the user interaction (i.e. how to carry out business tasks) rather than the internals (how the product works), which you should be, you might find you can start reasonably early, while of course picking up on any design changes in the scrums.
I think there is some confusion on what Agile terms as “documentation.”
My understanding is that when agile refers to minimizing and referring and documentation, it is referring to documentation internal to the the project–i.e., the documentation the developers use to plan and guide their project. I think traditional project management and also RUP produce a lot of project planning documentation.
However, something like the user guide for the product should be in the same category as a product feature and should be started early and iteratively like any other feature/deliverable.
Agile doesn’t really address user documentation, apart from an overall philosophy of the minimum viable product. The problem with starting early is there often isn’t anything to document at the start, as there’s next to no technical specifications and a prototype that is likely to change significantly before it’s completed.
One of the key principles of Agile is early and frequent delivery to the customer. If the end user actually needs documentation (as opposed to it being created as a formality to meet commercial or regulatory requirements) then you can’t really make those early and often deliveries of product without also delivering documentation of the features you are delivering in each iteration. If the delivery of end user documentation can be delayed until the final delivery, that suggests that the docs are not actually serving any useful purpose.