design documents

Islandora Software Design Documents

General Thoughts

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.

Section 1 – State the purpose of your project/sub-system. (Project requirements)

Audience: Peer Developer, Manager

Written By:

• This helps define the requirements of the system
• It is sometimes helpful to state the anti-requirements as well. Things that will not be done in this iteration of the software.
• A few paragraphs
• What problem is it trying to solve
• Why does it need to exist
• Who will use it?
• Thoroughly explain the design philosophy and intentions
• Think about:
  • User Requirements
  • Technical Requirements
• Convey design decisions
  • advantages
  • risks
    • risk mitigation
• Create a common vocabulary
• 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.

Section 2 - Define the high level entities in your design

Audience: Peer Developer, Manager

Written By:

• Define the high level components of the design.

Section 3 – For each entity, define the low level design:

Audience: Peer Developer

Written By:

• Usage
• Configuration
• Model
• Interaction
• Its fairly important this this section be clear, complete, and well defined.

Section 4 - Benefits, Assumptions, Risks/Issues

Audience: Peer Developer, Manager

Written By:

• 5-6 top benefits of the design
• a list of ALL known risks/issues
• list of ALL assumptions

Section 5 - Testing Plan

Audience: Peer Developer

Written By:

• How are we going to test this beast
• Are unit tests appropriate
• Is user testing more appropriate
• Is this component testable? If not we will have to redesign it so that it can be tested.

References: 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