design documents

Islandora Software Design Documents

Introduction

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.”

General Thoughts

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: When implementing the sandwich routine make sure that the cheese gets melted.

The Actual Document

Section 1 – Requirements and Problem Description

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. This section could also be called: 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.

Section 2 - Design Philosophy

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 being designed in the way that they are and the problems that they are trying to solve.

This section should talk about the technologies that are being used, and the perhaps introduce some of the high level components of the design.

• 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 3 – For each entity, define the low level design:

Audience: Peer Developer

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

Section 4 - Benefits, Assumptions, Technologies, 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.

Example Design Documents

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.

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