List of project members and their contact information.
Tenets are a list of guiding principles for your project. Your tenets will keep you focused on your objective and keep you heading in the right direction.
Tenets are independent of each other, are clear and memorable. They are used to define what a team cares more about.
Tenets are used to to help make difficult choices and trade offs in design decisions.
A high-level paragraph explaining the purpose of the document. This should be written with the scope that anyone in the company can view this document and have an understanding of the proposal. Include a summary of the problem, any background information and the proposed solution.
What will make this project successful? This can be listed as a bullet point list of key features, workflows, and qualitative metrics; such as increasing performance by X%. These measurements should not be considered pass/fail, but rather used in the retrospective to probe further questions into the system if needed.
A list of things that you will do / address / solve as a bullet point list.
A list of things that you will not do / no address / not solve as a bullet point list. Sometimes it is easier to start with this before writing what is In Scope.
List of issues that you currently do not know how to solve. When having a design document review, these issues should be addressed and solutions proposed.
Create an architecture diagram of your proposed system including any external systems that it will interact with. For more information on Use Cases visit the Wikipedia article.
Write about how your solution works in a detailed narrative, refer to appendices for diagrams, APIs, data structures, database schemas, etc.
Describe any alternative solutions that you may have prototyped. Compare these alternative solutions to the proposed solution. List off the pros and cons of each solution, and why the proposed solution is the one you decided to go with.
List any external dependencies that your solution has, and why.
A list of properties that can be expressed as “the system must do ”. The requirements should be measurable. Think of metrics. E.g.:
- Users should be able to easily download prediction results.
- The system should have a logically defined API.
- The service should be able to handle 10,000 concurrent users.
A list of properties that can be expressed as “the system shall be ”. E.g.:
- The system shall be secure
- Maintaining the system should be well defined and simple
- The service should be easily extendible, its components should be modular.
Some categories which non-functional requirements can be placed in are:
- Security
- Extendability / Maintenance
- Scalability
- Availability / Resilience
- Performance
Define metrics for both functional and non-functional properties of your solution.
Define your alarms based off of the metrics above.
Include things such as:
- Glossary
- FAQ
- One pagers
- API definitions
- Database Schemas
- Links to dependencies
- External documentation
Another great resource which @iamed2 had found,