Posts Tagged ‘documentation’

You’re Doing It Wrong: Automating Documentation

Wednesday, June 18th, 2008

I recently came across the article Automation for the people: Pushbutton documentation at IBM developerWorks. Let me start out by saying I am a fan of automation and that automating the creation of source code documentation, user documentation, and build diagrams is fine in my book. What annoyed me was the automated creation of UML and entity-relationship diagrams. Scratch that, it wasn’t the automated creation of them, because that can have its uses, it was the implication that the creation of these diagrams was tangential to development and so we should just write the code and generate the docs.

UML and entity-relationship diagrams help us develop code. If you find that they need to be changed at the implementation stage then you should go back (as painful as it may seem) and fix the problem at the design stage. In the long run you’ll be much better off. I can hear people complaining already in that I am not following my own advice and following good design practices for the snake game, and they are right. However there is a difference in that the snake game is just something I’m doing to explore Haxe. So I want the flexibility to change the design as I learn the language and its features. If this were a serious project you bet I would be following good process.