You might have heard that the beards who devised the Agile Manifesto banned comprehensive documentation. But their principle is: they appreciate comprehensive documentation but they prefer working software. And I do too. But I really like good system documentation (almost as much as I love working CRM software). Have you ever been asked to support or extend working software with no documentation? I have. I hate having to do that. I associate my best agile CRM projects with great documentation. And some of the worst CRM projects I've had to turn around had terrible documentation.
Approaches to writing CRM system documentation
I've used three approaches to writing great documentation in an agile project:
- Wait until a 'hardening sprint' or some other time to produce system documentation. [Edit: I don't use special sprints for several years, and I don't recommend them]
- Encourage the product owner to prioritise documentation chores in the product backlog throughout the project.
- Include documentation in the project's definition of done.
Including documentation in the definition of done has worked better on my projects and it’s a technical practice that I recommend to my clients. I encourage you to try it too.
System documentation I recommend
What documentation should a story have before it’s declared done? Every project’s definition of done needs to be agreed between you and your product owner. Velocity is lower when there’s lots of documentation to produce, but appropriate documentation can improve the overall quality of your product.
I like to ensure there is a:
- User Guide updated with each new feature so that users can learn the system
- Test Case for each new feature so users and testers can validate the feature
- Design Statement so that everyone knows what customisations have been performed on the system
Design statements rather than design specifications
I recommend design statements rather than specifications. Don't document what you intend to build in a design specification. Instead document what you have built in a design statement. Better yet, jot down why you did it too. Design specifications attempt to predict how the solution will be implemented but they are often inaccurate, ambiguous, incomplete, and they rarely get updated after the customisations have been performed. I've seen design specifications describe entities whose names are different in production, security roles that don't exist and entire integrations that were never built.
A design statement describes how the solution actually works in its current state. I can produce most of the details for my design statement in 10 minutes using Snapshot! for Dynamics CRM. I can run Snapshot! at the end of every sprint so that we always have an accurate, complete, clear and up-to-date record of the system. I can even compare the design statement from two separate sprints to see exactly what’s changed over time.
Do I ever write design specifications? Sure, sometimes when our enterprise architect group or some other policy wonk is holding a gun to my head. I’ll outline my intended CRM system design but I’ll focus on the standards they are looking for: security, interoperability, and supportability.