Architecture/Design documentation
Architecture documentation is a special breed of design document. In a way, architecture documents are third derivative from the code (design document being second derivative, and code documents being first). Very little in the architecture documents is specific to the code itself. These documents do not describe how to program a particular routine, or even why that particular routine exists in the form that it does, but instead merely lays out the general requirements that would motivate the existence of such a routine. A good architecture document is short on details but thick on explanation. It may suggest approaches for lower level design, but leave the actual exploration trade studies to other documents.
Another breed of design docs is the comparison document, or trade study. This would often take the form of a whitepaper. It focuses on one specific aspect of the system and suggests alternate approaches. It could be at the user interface, code, design, or even architectural level. It will outline what the situation is, describe one or more alternatives, and enumerate the pros and cons of each. A good trade study document is heavy on research, expresses its idea clearly (without relying heavily on obtuse jargon to dazzle the reader), and most importantly is impartial. It should honestly and clearly explain the costs of whatever solution it offers as best. The objective of a trade study is to devise the best solution, rather than to push a particular point of view. It is perfectly acceptable to state no conclusion, or to conclude that none of the alternatives are sufficiently better than the baseline to warrant a change. It should be approached as a scientific endeavor, not as a marketing technique.
A very important part of the design document in enterprise software development is the Database Design Document (DDD). It contains Conceptual, Logical, and Physical Design Elements. Database Design Document includes the formal information that the people who interact with the database needs. The purpose of preparing the DDD is to create a common source to be used by all players within the scene. The potential users are:
Database Designer
Database Developer
Database Administrator
Application Designer
Application Developer
When talking about Relational Database Systems, the document should include following parts:
Entity - Relationship Schema, including following information and their clear definitions:
Entity Sets and their attributes
Relationships and their attributes
Candidate keys for each entity set
Attribute and Tuple based constraints
Relational Schema, including following information:
Tables, Attributes, and their properties
Views
Constraints such as primary keys, foreign keys,
Cardinality of referential constraints
Cascading Policy for referential constraints
Primary keys
It is very important to include all information that is to be used by all actors in the scene. It is also very important to update the documents as any change occurs in the database as well.
