Agile was the big thing years ago, and just like how to can’t really “do” agile, but you can follow the principles of Agile and
if you follow them all then you will reap the benefits, however if you miss just one of the principles then the challenges can outweight the benefits.
Documentation… The bane of many developers and architects, who would rather write code or prototypes, maybe even tests or bug fixes. Documentation has been a topic of great controversy, pitting Agile against Waterfall. There have been many attempts over the decades to replace technical or functional specifications with Domain Specific Languages (DSLs) that can auto-generate code from a written document. What is unfortunate is that the value of good documentation is lost in the mix usually because of some common pitfalls.
Pitfall # 1 –The goal and reasoning behind documentation is not clear.
Pitfall # 2 – The value of the documentation is not usually given to those who create it, and ultimately it is usually a lower priority than code and as a process is usually not followed so code and documentation get out of sync.
Pitfall # 3 – Developers have not been training appropriately around good practices, and guidance, these are usually given to analysts and project managers, who don’t know the code or technical capability as well.
Pitfall # 4 – Time…. usually as a lower priority no time is given to documentation and many modern practices (Agile) value readable code over documentation (Thought I would argue a functional specification is similar to a story, but perhaps more technical in business terms.)