Few people really like documentation. Given the option most would rather try to figure out what to do without reading the manual. Even quick reference guide is hurriedly tossed aside to tryout the latest gadget. It’s probably masculine pride and could account for the agile manifesto’s preference for face-to-face communication over written documentation. I’m not saying the agile manifesto favours masculine traits but it’s true the initiators were all male (http://agilemanifesto.org/).
When a new member joins an agile project face-to-face communication is essential to gain understanding of the system its foibles and its characteristics. There’s likely to be little or no documentation to read. Agile modellers may have left behind some light weight foot prints in the form of iPhone whiteboard snaps or maybe a few diagrams, most likely rendered in HTML and accessible only via a browser. But these are rarely up to date, refactoring and continuous delivery will have seen to that. So to return to the question often debated by projects embarking on an agile course, “Should we produce any documentation or not?” Well, it depends…
Given a stable agile project team there’s little benefit in documenting much before coding. Simple user stores capture outline requirements sufficient to continue conversations between developers and business specialists. The story’s success criteria keep QA busy with enough to write test cases and outline scripts. After several iterations and releases all the team are in sync so there’s little perceived benefit in retro documentation and the overhead associated in keeping it in sync. Inevitably team members wax and wane and new requirements challenge the agile approach. The Business, flushed with success of early versions may see new opportunities for additional features way beyond the original requirements. These aspects stress an agile project. Without documentation new members must spend time with experienced team players but those left are over utilised in responding to change requests and bug fixes and can spare little time for the newbies. Without a high-level architectural schematic it’s difficult to discuss the brittle points for the new requirements and the developers talk code rather than packages. (Code has its place but not usually at meetings between the business, architects and project managers discussing the latest marketing ideas for product offerings.)
Documentation helps support the frailty of human memory and schematic models can focus and simplify discussions so that all are on the same page. In the truest agile way these can be generated from a model or created on a whiteboard and don’t have to be lengthy tombs. I’ve found a few core diagrams can be extremely helpful. For example, in a message based order processing application, a state diagram showing the states of an order with its associated events can form the basis for planning development, partitioning stories and organising test cases. While a high-level block schematic can define architectural boundaries and help allocate development teams and identify message interface owners. There’s often little need for pages of descriptive prose or endless sequence diagrams. But one or two physical data models depicting the cardinality between major entities can again focus discussions and ultimately speed development.
