design documents

Islandora Software Design Documents

Introduction and Notes

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.

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. No special tools are needed. 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.

This process (potentially should) be done in stages, corresponding to each section, possibly with feedback from the appropriate people between each stage. This will produce a more complete document.

• Convay design descisions

  • advantages
  • risks
    • risk midigation

• Good place to start is the requirements

• Create a common vocabulary

• 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. However this effort makes it much harder to overlook probelmatic issues. 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.

• This is a quote from a page referenced below that I paricularly like: 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.”

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

• 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. I find this extremely important for the readability of technical documentation. I think we need a template in whatever system we decide should be holding technical documentation, which aids in creating a readable document using styles.

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

Section 1 - Rehash of the project requirements. Technical Requirements User requirements Lifecycle

• Developed by the project manager (Audience: Peer Developer, Manager)

Section 2 – State the purpose of your project/sub-system (Audence: Peer Developer, Manager)

• A few paragraphs
• What problem is it trying to solve
• Why does it need to exist
• Who will use it?
• Thouroughly explain the design philosophy and intentions

Section 3 - Define the high level entities in your design (Audence: Peer Developer, Manager)

Section 4 – For each entity, define the low level design: (Audence: Peer Developer)

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

Section 5 - Benefits, Assumptions, Risks/Issues (Audence: Peer Developer, Maanger)

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

Section 6 - Testing Plan

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

*** Colorado Post-mordem / Company process in general ***

Food for thought: http://www.joelonsoftware.com/articles/fog0000000043.html

I believe that I should write a post mordem on colorado and submit it to John, Mark and Paul.

Some elements of this would be fantastic to include: Do you fix bigs before writing new code? from the above article.

• On the Excel team we had a rule that whoever broke the build, as their "punishment", was responsible for babysitting the builds until someone else broke it. This was a good incentive not to break the build, and a good way to rotate everyone through the build process so that everyone learned how it worked. I tend to like an approach like this rather then large blocks of metal :P

{Why our approach to refactoring islandora may be incorrect} http://www.joelonsoftware.com/articles/fog0000000069.html http://www.joelonsoftware.com/items/2007/10/26.html