Our clients have different requirements\n with regard to design. Some want signed-off design documents before \nstarting development others are satisfied with as-built documents and \nsome think even that is overkill. Who is right? Or does it depend on \ncircumstances?<\/p>\n\n\n\n
Why design?<\/p>\n\n\n\n
Everything needs to be designed even if it is just made up on the fly by the developer(s). Do we want to document the design?<\/p>\n\n\n\n
Design is a conversation between the \nvarious stakeholders in the project \u2013 present and future. It may take \nthe form of a formal design document, or it may be 3 people standing \naround a whiteboard. The important point is that all finish with a \nshared understanding of what is to be built and why. The needs of \ncurrent participants are easily satisfied, but what about future needs? \n Does the design collateral help the people that need to maintain\/extend\n the software? What happens if someone leaves and takes their design \nunderstanding with them? <\/p>\n\n\n\n
Advantages of Formal Design Documents<\/p>\n\n\n\n
In formal engagements a signed-off design\n document forms the basis of a contract between the project sponsor and \nthe developers. The delivered software is tested against the \nrequirements, but code-reviews are matched to the design. The design \ncan be reviewed in advance to see that the planned approach meets the \nneeds of the project and fits the infrastructure before the expense of \nbuilding is incurred, and this can avoid costly rework.<\/p>\n\n\n\n
Where a large number of different parties\n are involved (business, infrastructure, networks, application \ndevelopers, testers etc) a formal design document gives everyone a clear\n picture of what their tasks are and how they are matched to the needs \nof the other parties. it allows a project manager to allocate work and \ncheck progress.<\/p>\n\n\n\n
For enterprise requirements (e.g. \nsecurity, performance, non-interference with other projects etc) a \ndesign document gives peripheral actors a chance to have their input. \n This is important where strong governance processes are in play. \n Everyone can have confidence that their needs have been considered \nbefore signing off.<\/p>\n\n\n\n
The design document provides a place to \ndocument the design decisions that were made. It is important for \npeople who come later to understand the reasons for choosing various \noptions. This avoids relitigating decisions but also allows a \nre-examination of the options when conditions change.<\/p>\n\n\n\n
Advantages of Informal Design<\/p>\n\n\n\n
in smaller projects a design document may\n not be needed. A daily standup can provide a forum to discuss any \ndesign decisions required. The outcome should be recorded in the \nproject backlog. Comments in the code and\/or scripts should be used \nliberally to allow future participants (or current ones with \nnon-exceptional memories) to understand why things are done. This can \nprovide the needs of documented design without the overheads. <\/p>\n\n\n\n
A decision can be made in the morning and\n incorporated in code, checked in, built and tested all the same day. \n This way the documentation is always up to date. The documentation is \nalways available as it is saved in the CMDB with the source. Depending \non the tooling used the documentation can often be extracted (e.g. \njavadoc) and made available at the end of a project without the expense \nof developing as-built documents.<\/p>\n\n\n\n
Where should design be stored?<\/p>\n\n\n\n
Often organisations have formal document \nmanagement or record keeping systems for design documents. It is often \ndifficult to find the most up-to-date version and often even the most \nup-to-date version is not updated during the project so doesn\u2019t reflect \nwhat was actually built. This can be a problem for later projects as \nthey have to undertake an expensive discovery phase to find out what the\n real state is. Mature organisations can handle this, and it may be \ncorrect for them.<\/p>\n\n\n\n
In general the documentation should be \nstored in the CMDB along with the code. The same \nversioning\/branching\/tagging processes that make source code management \neasy, ensure that the documentation matches the deployed artefacts. \n However, they don\u2019t ensure that it is up-to-date. A design document \nshould always be supplemented by access to code and deployed artefacts. <\/p>\n\n\n\n
A good project-close-out process will \nhave a supplementary document describing what was actually built. This \ncan be an appendix to the design document describing variations and \nreasons for them. This can also be a separate as-built document. At \nthe least it should be release notes with a manifest of deployed \nartefacts along with where to find the (commented & versioned) \ncode\/configuration items.<\/p>\n\n\n\n
Design for Integration<\/p>\n\n\n\n
Integration projects have particular \nneeds. There are always several different products involved. A clearly\n defined interface is almost always required up-front.<\/p>\n\n\n\n
If new integration applications are \nrequired then the project looks like any software project with \ninfrastructure, software, networking requirements. The organisation\u2019s \nnormal design processes are used.<\/p>\n\n\n\n
For service development, the design needs\n to articulate the different parties involved in the service and how \nthey interact. Parts of the design (e.g orchestration, mediation) are \noften dependent on the product set used as they will normally have \ngraphical design tools that match design to implementation. The \ninterface and data design will usually use some sort of entity design \ntool like Sparx EA.<\/p>\n\n\n\n
It is useful to have a catalogue of \nservices in use and how they interact. This can be a spreadsheet, but \noften the linkages are more involved and a 2 dimensional table cannot \neasily represent them. A graph database may be an option to capture all\n the dependencies.<\/p>\n\n\n\n
Conclusion<\/p>\n\n\n\n
There is no right answer for how to \ndocument design. That is no excuse for assuming that no design is \nnecessary. Sometimes it is only after the project is finished (and the \nnext one underway) that you know whether your design strategy has been \nsuccessful.<\/p>\n\n\n\n
One thing is always true. Design is \nnever \u201cfinished\u201d. Even in a waterfall process with signed-off designs \nbefore coding starts there will always be further design decisions to be\n made as the project proceeds. the design process should recognise this\n and make sure that whatever is produced is still of value at the end of\n the project.<\/p>\n","protected":false},"excerpt":{"rendered":"
Our clients have different requirements with regard to design. Some want signed-off design documents before starting development others are satisfied with as-built documents and some think even that is overkill. Who is right? Or does it depend on circumstances? Why design? Everything needs to be designed even if it is just made up on the … <\/p>\n