I have been tasked with designing the new features we shall be implementing for the next release of our software application suite. There is a lot of flexibility in this task. The main principle I have been following is putting myself in the programmer’s shoes. I ask myself what information I would personally have liked to be done at the design stage. That is what I strive to determine and document at the design stage.So far I write in English the process logic I expect to be followed. This gets a little technical. It drills down much deeper than a business or even a system requirement. I also go further and write up some pseudo code. This is where I get very specific and call out table and column names from the database. These steps are no brainers. I do them for every change I design.
I also do user interface mock ups and add them to the design document. This will help us communicate the design to the customer. It will also help keep development and the customer on the same page. This part does take a while do to. I need to actually code up a prototype user interface to generate the screen shots. But I think it is worth it.
Finally I go to traditional design techniques like generating class and sequence diagrams. These might be useful to a junior developer that does not know how to knock out classes. And a sequence diagram might be good for those situations where we need to integrate the new code with a lot of existing code. I can lay out all the existing call stacks and show where the new stuff is supposed to fit in. However I sometimes feel that this is overkill if I am drilling down the new stuff in such a detailed way.
Perhaps correct design is supposed to do all the work so that coding is a mundane task. This certainly will reduce risks at the coding phase. But it shall also decrease the fun during the coding phase. It might be necessary based on the very short duration for the coding phase of some changes this year. But in one change I purposefully left out a lot of the new code details. This was done in good faith. I figure that the portion that accesses the database should be coded up according to the skills of the developer. If they know Oracle Pro*C well, this is what they should use. However if they are good in OLE DB, I do not want to tie them down to Pro*C at the time of design.
