Software (architecture) design document (technische ontwerp)

Source: Steve's blogs http://soa-java.blogspot.com/

Why writing design documents:
• to communicate design decisions and why
• to document the benefits & risks of your design
• to serve as a written contract (between you, your manager, your team, product manager, client / product manager): to limit changes, #works, risks.
• to provide common terminologies
• to facilitate peer review / feedbacks from shareholders, to minimize unexpected risks by addressing them before implementing the code

---

An exhaustive table of contents:

1. doc purpose, terminology, reference, distribution list, version,

2. high level summary: purpose/problem/why, who will use, gap analysis (condition now vs advice/solution)

3. scope: benefits, assumption, risks/issues, relation with other projects/dependency, standards
4. requirements:
o use cases:
 actors
 trigger
 preconsitions
 postconditions
 priority
 level: user-goal/sub-function/summary
 frequency
 type: interactive/batch/interface
 flow (basic flow, alternative flow, error handling flow): what the user does & system response, not how/why
 data dictionary (e.g. what the user enters in the UI):
o field name
o type (input,output)
o required y/n
o format: Numeric, texts, y/n, enums
o validation
 special requests (e.g. browsers & resolutions, availability)
 storyboard: to show user expectation of system behaviour e.g. GUI information presented to the user/entered by users, actions/requests which users can perform, screenshots
o other (non-functional) requirements (e.g. performance, legal, licence, security, tools, standards, compatibility with legacy system, 3rd party, OS/environment)

5. high level design/ system architecture (4N+1+more):
o logical view: list of main elements: roles/responsibilities/interactions, architecture diagram, organization (subsystems, layers), frameworks
o design constraints: application type (e.g. web apps, webservice), architecture style (e.g. layered, domain driven, soa), technologies (e.g. languages/framework, database vendor, OS) , compatibility, dependency, corporate policies, standards
o design trade offs/rationale / use-case view / traceability, for example:





o implementation view: artifacts/executables, module/package structure
o process view (concurrency, synchronization)
o (human) business process: (can refer to use-case)
 forms: sample forms, handling
 procedures: trigger/conditions, handling-steps/order/process-diagram, data needed, business rules, expected results, time limit, error handling
o quality attributes:
 security concerns: authentications/authorization mechanism, encryption, password (min strength, expiration), database/file-system access level (read only, write)
 performance (e.g. response time, load/throughput): goal (e.g. response 5 sec with 100 sessions), degradation mode (e.g. response 5-10sec with 150 sessions), measure, correction action (e.g. if timeout then show a "please try again later" page)
 reliability: transaction/locking, validation, defect rate (e.g. product is accepted when no critical bugs left in the buglist), accuracy, recovery, restart, mtbf (max time before fail), mttr (max time to recover) , error handling, logs, troubleshooting / error code
 usability/user friendliness: resolution, browser, font/color, standardization of GUI components & terms, help/user-manual, max time to complete task, training requirement)
 maintainability/scalability: log, doc, standard, parameterization (e.g. internationalization, changing contents/config)
 availability
 reusability
o crosscutting concerns (e.g. cache, authentication, communication, exception management, log) and how to address this issue (e.g. aspect oriented programming)
o test: risk-level & tests per design aspects/requirements/usecase ,techniques/framework (e.g. selenium GUI test, jmeter stress test)
o deployment view: hardware/networks/software configuration (e.g. database, mds, firewalls, clusters, soa/clouds configuration), compatibility, protocols (e.g. https, soap), deployment-settings, configuration management (e.g. via console/file/centralised-server), installation procedure

6. low level design (e.g. for GUI/presentation layer, business classes, webservices, database layer):
for each subsystems describes:
o role/function
o artifacts (e.g. jar/war/dll), how to be used (e.g. webservice, lib, web application)
o input/output, interface (e.g. webservice or lib)
o constraints: dependency, framework
o class diagram
o sequence diagram, process view (concurrency, synchronization)
o business process diagram
o error handling
o configuration (e.g. hardware/software/version needed, wsdl)
o for UI components: screenshots, screen objects, actions, events, files/classes (templates/jsp/php), resolutions & browsers
o for data objects: how to store/datasource (e.g. database/file), process, data(class) dictionary (type, description, attributes, methods), tabel dictionary (data type, keys/contraints), data model/tabel relationship diagram, accessibility/security
o unit tests

7. planning: development schedule/time, development cost, development organisation (e.g. resources/skills-needed/roles, raportage/meetings), procurement/cost(hardware/software/tools/licence/workplace/training)

---

Tips:
• some items in the content list above are optional and can be removed due to duplications (with similar items within this document or with other documents such as statement of work/SOW, product requirement doc/PRD, plan)
• you can separate the contents to several documents for several target audiences (e.g. use case doc, PRD, software architecture doc, product acceptance plan, test plan, development plan). Personally for small projects (less than 100 thousands euros / 400 man hours) I prefer to write a single document as concise as possible (less than 20 pages) instead of writing 6 separated documents.
• you don't have to be 100% UML compliance, the diagrams are just supplements
• don't try to be perfect in the first iteration, the design document is a living document, keep your document lightweight/easy to update
• provide unique identifier for design elements (e.g. usecase, requirements) so you can refer to
• Suppose as an architect you need to write a design document for your developers, how much details should you put in your design document? The amount of design work and the formality of that work depend on two factors: the expertise of the project’s developers and the difficulty of the project. If the project has expert programmers and is a simple project, the design can be less detailed. But if the project has inexperienced programmers, uses unfamiliar or untested technology or demands high reliability, then a more detailed design approach may be warranted.

Any comments are welcome :)

---

References:
• Software Project Survival Guide by McConnell

• Microsoft Application Architecture Guide

• Applying UML and Patterns by Larman

• http://blog.slickedit.com/2007/05/how-to-write-an-effective-design-document/
• How to Write a Software Design Document by Alissa Crowe-Scott http://www.ehow.com/how_6734245_write-software-design-document.html
• RUP op maat by Dekker