-
Notifications
You must be signed in to change notification settings - Fork 118
design documents
I would like to start by saying none of this is set in stone, the point of writing this document is to put some process down on (digital) paper, so that we can all collaborate on making it better. Every project and every design is different, so these are just guidelines, use your own best judgement. This page has been cobbled together from discussions with others, my own thoughts and some internet references.
This process should be done in stages, with a different person responsible for the content at each stage. Even though each sections content will be created by different people, one person needs to "own" the document, so that someone is responsible for making sure it is up to date, and all the appropriate sections get created. This will produce a more complete document.
A large portion of the work of a design document is the front loaded effort of processing the ideas and converting them into a design. This effort will include some prototyping and investigation. This effort makes it much harder to overlook issues that will be faced in the implementation phase. It also allows for some peer review before the development effort. Its much easier to move blocks in a diagram then refactor hundreds of lines of code. If done properly design should make the implementation phase much easier.
The hardest part of writing a design document has nothing to do with the writing. The difficult part is working through a logical design before you get to coding. Once you have a vision of how the objects and entities are arranged, writing the details is easy. In addition, it should not require anything more than a word processor and a simple shape painting program. The positive difference that spending a week on this task can make is unbelievably rewarding in the end. As the adage goes:
“If you fail to plan, then you plan to fail.”
Diagrams are important, they help the reader understand the interaction between the various components. You can however draw the diagrams in any tool you wish. If you want to use UML in your document that is fine, interaction and class diagrams are useful, but this document should capture the essence of your thoughts while developing this solution, and more important then UML diagrams. Overly complicated diagrams are often miss the forest for the trees. The biggest factor that determines if your design document is good is whether or not it clearly explains your intentions.
As the project evolves so should the design document. When due to time restrictions various features are being put on the chopping block, the design document should serve as the place to start these discussions, and be updated. This has the advantage of giving someone starting the phase ii development a design document with many issues already thought out.
Trivial, but often neglected: Use a consistent notation, a consistent terminology, different fonts for different purposes, white space between paragraphs and between sections, indentation. This is extremely important for the readability of technical documentation. It would be helpful to eventually create a template in whatever system we decide should be holding technical documentation, which aids in creating a readable document by having predefined styles for the various technical information. In this regard google documents falls flat on its face. There is no way to: define styles (for example a text style for variable names or module names), enter equations, make templates, give graphs figure numbers and I find the drawing tools very primitive. We need as a team to decide what we are going to use.
Avoid using lists of cryptic nouns. As tempting as it may be to quickly jot down your ideas, a design document written in shorthand will not convey your thoughts and intentions to the readers. Instead, it will cause misconceptions and misinterpretations. Theses shorthand notes can help when writing the document, however they need to be expanded upon before the document is passed on to others.
Finally throughout the document care should be taken to create and maintain a common vocabulary that can be used when discussing the project. If necessary new terms should be defined, so that everyone on the team can discuss the project without getting into semantic arguments about what things are called. If the document is defining a lot of new vocabulary when it is often a good idea to also create a glossary section.
It is often helpful to include notes in the document to the various people involved in the process. Using a different font, or style, so that they stand out can be helpful. Something like:
Implementation Note: We may be able to generate the RAW API PHP using the WDSL that is provided for the REST interface.
Audience: Peer Developer, Manager
This section reiterates the design requirements of the software being developed. It is sometimes helpful to state the anti-requirements as well if there are things that will absolutely not included in the design during this development cycle. State the purpose of your project/sub-system.
This section should only be a few paragraphs, if it is longer, then the problem you are trying to solve in this document may be too large to solve using a single project, it may be best to use this to describe the higher level problem, and then break the problem down into several smaller design documents.
It should describe the problem that this software is trying to solve, why it needs to exist and who will use it. Without a firm grasp on the problem that is trying to be solved there is bound to be miscommunications among the people working on this project. It provides everyone working on this project with an audience to, so they know who the work is aimed at.
This section can be broken down into a user requirements section, and a technical requirements section, depending if that is needed for the project at hand.
Audience: Peer Developer, Manager
This section is probably the most important section in the whole document. It thoroughly explains the design philosophy and intentions. Its very important to outline why things are designed the way that they are and the intentions on this design. This gives people insight in the future into the mindset when working with this project.
This section should also describe the technologies being used and explain why. We need to consider what technologies are currently being used, what the rest of the industry is using, and the training time to bring everyone up to speed on new technologies.
This section should talk about the technologies that are being used, and the perhaps introduce some of the high level components of the design.
Depending on the software you are writing, some of these sections may be applicable or not. They are just some suggestions.
Create a common vocabulary for use in the project. If there are a lot of terms being defined, this section can be very helpful so everyone on the team can be on the same page.
For projects that are creating user facing designs, this is very important. Typically people who write good code can't design UIs. Hell UI design is very hard, so the more eyes on the wireframes in this section the better.
I'm sure there are more I am not thinking of here.
Audience: Peer Developer
Some things to possibly include:
- Class definitions for all the external facing entities. This takes some design work, but its good to put together before actually writing code, allowing feedback before the entities are implemented. Potentially using UML class diagrams.
- Example use cases. Show the intended uses of APIs.
- Interaction. How does data move around in the design.
- Model. What sort of a data model are we using.
- Configuration.
Its fairly important this this section be clear, complete, and well defined.
Convey design decisions and the advantages and risks. This may be simply reiterating something mentioned in other sections, but its nice to have all the advantages and risks enumerated in one place. Include what can be / is being done to mitigate the risks mentioned. List ALL of the known risks and assumptions.
Care needs to be taken to explain the use of technologies and the advantages, risks and alternatives. This needs to take into consideration technology which is already used in the project, and the cost of bringing the wider team up to speed on the new technologies.
Audience: Peer Developer Written By:
How are we going to test this beast? What is the most appropriate type of testing? Who is going to do the testing? Is this component even testable as designed? Ideally this is written by someone who hasn't written the other sections of the document.
Here we should list the design documents that have been created for the project. Seeing an actual document makes it much easier to understand then reading a document about writing them. These examples so far are just things I have written for the project:
- https://docs.google.com/document/d/15VreK-pKY_8foxTeAYqVbAyWP8GWoFMqk4ElHmX-xkI/edit
- https://docs.google.com/document/d/1PA6JzjLFU3rx1aGJV9tZqLKxUfuoZCHUPlx2NN90hs0/edit
- https://docs.google.com/document/d/1O_Ylh-uc6i7ea2T9nC6HvopehKCfHWvp2TIuq7bN9FE/edit
http://blog.slickedit.com/2007/05/how-to-write-an-effective-design-document/
http://www.bitformation.com/art/writing_design_docs.html
Possible sample design document
http://www.bitformation.com/art/sample_sw_design_doc.html
You may be looking for the islandora-community wiki · new to islandora? · community calendar · interest groups