Well I have a couple weeks to build a design document and some use case realisations… it seemed easy enough. But having done very little design, I didn’t really know what these document were, I had plenty of examples, but for me the examples are pointless. I need to know why I was making the documents - I have documented and designed plenty of systems. And nobody seems to care a lot about the documentation quality, neither did I. Now I am interested, I want to know how these documents fit into the process and why we are following the process.
Personally I don’t agree with it, but that is one of the issues with following orders, you don’t usually agree with them!
So what is a design document, lucky there was a 100 level software engineering project on it in at the University of California, Santa Cruz… never went there but they have given me my first Google link on the topic. And provided a template of sorts. I don’t need a template exactly, I have plenty of content examples from other projects at work and a template to paste Enterprise Architect diagrams into - we can generate EA documents, but I don’t have a detailed design template for that… that I know of?
Well, unlike the project above, I won’t be doing any reverse engineering. It is all from scratch. What I do have to do is provide a web service interface for one C# web services application, a web service interface of a legacy application and interface with a proprietary Java web service interface. All nice and straight forward.
I also need to provide tools to do simple document manipulation, like concatenating files etc. And libraries for translating objects between the different standards implemented/expected by different services.
And surprisingly I have to provide a design to invoke applications using a scheduler and .bat or shell scripts (probably .bat - I’m not the architect).
So it should have.. an architectural diagram, UML structure diagrams, UML sequence diagrams and Explanations. You need to provide text providing an overview of the diagrams, and design choices embedded in these diagrams. Ideally, a reader who has previously seen your requirements and scenarios documents should be able to understand your design documents, based on the descriptive text you provide, along with the architecture and design documents. For example, while you do not need to provide a textual description for every UML diagram, you should explain how you made your modularization decisions (how did you choose your objects), the organization of the diagrams (why did you order the diagrams in a particular way), and any unusual or noteworthy design decisions (why you think your 8-level deep inheritance hierarchy is the right choice).
For an induction into UML models/design check out the UML tutorials page and also the Sparx UML tutorials, sparx make Enterprise architect. And I am interested to see Equinox run courses in this type of stuff in New Zealand…
