- Created by Robert Reiner, last modified on 14. Nov 2018
projectdoc Toolbox
Document a decision for an option. This is useful to state the reasons and the options that have been evaluated. Later other team members will have it easier to understand the decision.
- ID
decision- Suite
- Parent
- Documentation Type
- Categories
Properties
The document type decision provides the following properties:
Please note that only information about specific properties is provided here. Common document property used by all document types are documented by Document Properties.
Type
Group decisions by their type. A project may provide its own set of types via the Decision Type Doctype.
Sponsors
List the stakeholders that take special interest in this decision and therefore support the effort put into this.
Sections
Summary
Give a short summary about what has been decided. Add anything that is of interest for users having a brief look at this document.
Problem
Define the problem for which a decision has been made by the team. The problem has these subsections:
Details
Define the problem that this decision solves.
Relevance
Provide details why this is relevant for the project and why it should be documented to be referable later.
Implication
Provide details what implications this decision has on the project.
Problem Constraints
Document constraints on the problem that influence the decision. These constraints are described in the following subsections:
Requirements
Illustrate the functional and non-functional-requirements that constrain the decision.
Drivers
Provide details what other drivers are relevant for the decision.
Risks
Provide details which risks are involved for the decision.
Assumptions
Decisions have to be made in situations where not every information detail is available. Otherwise the path to take would be clear without any doubts. To close the gaps between known and unknown assumptions have to be made. This section allows to document the assumption so that the decision is better understandable later.
Description
Provide details which assumptions have been made to make the decision. It is assumed that assumptions cannot be proven else this would be a requirement or not mentioned if proven invalid.
Check Assumptions
Describe strategies how the given assumptions can be proofed or refuted?
Risks
List the risks you assume this assumption has.
Alternatives
Provide a list of alternatives that have or have not been examined.
Decision
Provide information about the decision that has been made.
Statement
Define what has been decided to do. This should be a brief statement since this is also rendered in the index document.
Reason
State what reasons led to the decision.
Implication
Provide details what implications this decision has on the project.
Date
Specify the date of the decision.
Deciders
Provide a list of stakeholders that made the decision. If there is uncertainty about why this decision has been made, these stakeholders may provide additional information at a later time. Consider then to include this information in this document.
Subordinate Decisions
Add decisions to this decision as child documents if these decisions are in a close relationship.
Notes
These are internal notes that are usually not exported and only visible to team members with write access.
But this is not a safe place to store sensible information. It is just a convenience for the reader to not be bothered with notes stored here for the authors for later use. The security level is about suppressing the representation by a CSS style. Therefore consider this as a convenience for the reader, not as a security tool.
The text of notes sections is also indexed.
References
For a document the references section contains pointers to resources that prove the statements of the document.
Often these proofs are not easily distinguishable from further information. In this case you may want to skip the reference section in favour for the resource list.
For further information please refer to References and Resources.
Resources
The resources section provides references to further information to the topic of the document.
This may be information on the internet provided by the resource or information in the team's information systems. Anything the reader of the resource might want to know, may be listed here.
For further information please refer to References and Resources.
Related Doctypes
Decision Type
The Decision Type Doctype to categorize specifically on decisions.
The type 'marketing' may tag decisions to be relevant for the marketing of the product.
Alternative
Alternatives may be documented with the Alternative Doctype in greater detail if it is relevant to have the research results available for later reference.
Architecture Decision
The Software Development Doctypes Add-on has a doctype to document decisions for the architecture (Architecture Decision Doctype) of a software system.
Resources
- For a more detailed introduction to architecure decisions, please refer to Stefan Zörner's book Software Architekturen dokumentieren und kommunizieren, chapter 3.
