Technical Writing: Writing a good functional specification.

January 11, 2012 by · Leave a Comment
Filed under: Business, Design, Uncategorized, Writing 

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.)