1.
Front matter
Title
Author(s)
Team
Reviewer(s) (if applicable)
Created on
Last updated
Epic, ticket, issue, or task tracker reference link
Repository (Link to your GH repo)
2. Introduction
a. Overview, Problem Description, Summary, or Abstract
Summary of the problem (from the perspective of the user/customer), the context,
suggested solution, and the stakeholders.
b. Glossary or Terminology
New terms you come across as you research your design or terms you may suspect your
readers/stakeholders not to know.
c. Context or Background
Reasons why the problem is worth solving
Origin of the problem
How the problem affects users and company goals
Past efforts made to solve the solution and why they were not effective
How the product relates to team goals, OKRs
How the solution fits into the overall product roadmap and strategy
How the solution fits into the technical strategy
Note: The bullet points above are suggestions of what can be covered in this section. Not all of
those points are applicable to every project.
d. Goals or Product and Technical Requirements
Product requirements in the form of user stories
o Ex.: As an instructor I want to download student submissions so that I can open it
on my favorite file editor/viewer to grade them.
Technical requirements
o Examples:
o The system shall be compatible with Chrome and Firefox latest versions.
o The system shall offer a responsive mobile-friendly user interface with the exact
same functionalities.
o The system shall be hosted on the cloud without needing installation on customer
locally owned servers.
Note on terminology: In this template, product requirements are functional requirements,
whereas technical requirements are non-functional requirements.
e. Non-Goals or Out of Scope
Product and technical requirements that will be disregarded.
f. Future Goals
Product and technical requirements slated for a future time.
Note: It is fairly common that
o requirements fluctuate between sections ‘d’, ‘e’, and ‘f’ over time as the
document is created and revised from early to late stages in the product
development lifecycle.
o at some point in time (and especially in the beginning of a project) you many not
clearly know where to place a requirement either in section ‘d’, ‘e’, or ‘f.’ Do
your best judgment in consultation with your team and in contact with
users/customers/stakeholders.
g. Assumptions
Conditions and resources that need to be present and accessible for the solution to work
as described.
3. Solutions
a. Current or Existing Solution / Design
Current solution description
Pros and cons of the current solution
Note: This refers to current or existing solution in house or provided by external organizations
or open source projects. Also, if you are designing a new feature or a new release for an existing
product, describe the current solution as-is and its pros and cons.
b. Suggested or Proposed Solution / Design
External components that the solution will interact with and that it will alter
Dependencies of the current solution (if applicable)
Pros and cons of the proposed solution
Structure and behavior diagrams to represent the design.
Data Model / Schema Changes (or the new one if it’s a new product)
o Schema definitions
o New data models
o Modified data models (if applicable)
o Data validation methods
Business Logic
o API changes (or the API itself if it’s a new product)
o Pseudocode
o Flowcharts
o Error states
o Failure scenarios
o Conditions that lead to errors and failures
o Limitations
Presentation Layer
o UX changes (if applicable)
o UI changes (if applicable)
o Wireframes with descriptions
o Links to UI/UX prototypes
o Mobile concerns
o Web concerns
o UI states
o Error handling
Other questions to answer
o How will the solution scale?
o What are the limitations of the solution?
o How will it recover in the event of a failure?
o How will it cope with future requirements?
Note: The subitems above are suggestions of what can be covered in each of the major items.
Not all of those subpoints are applicable to every project, but all the major items are
expected to be covered in this document.
c. Test Plan
Explanations of how the tests will make sure requirements are met and whether there is a
minimum bar for a standard test coverage.
Unit tests
Integrations tests
Other types of tests (e.g., End-to-end tests or Acceptance tests, Exploratory tests,
Penetration tests, etc.)
d. Alternate Solutions / Designs
Short summary statement for each alternative solution
Pros and cons for each alternative
Reasons why each solution couldn’t work
Ways in which alternatives were inferior to the proposed solution
Migration plan to next best alternative in case the proposed solution falls through
Note: This section refers to alternate solutions to be implemented by the team and not
alternate solutions already provided either in-house, in the market, or opensource.
4. Further Considerations
Some questions to be considered but not necessarily as a comprehensive list. Some questions
make more sense than others depending on the nature of your project.
Pick at least two to address in your class project technical specification.
a. Security considerations
What are the potential threats?
How will they be mitigated?
How will the solution affect the security of other components, services, and systems?
b. Privacy considerations
Does the solution follow local laws and legal policies on data privacy?
How does the solution protect users’ data privacy?
What are some of the tradeoffs between personalization and privacy in the solution?
c. Regional considerations
What is the impact of internationalization and localization on the solution?
What are the latency issues?
What are the legal concerns?
What is the state of service availability?
How will data transfer across regions be achieved and what are the concerns here?
d. Accessibility considerations
How accessible is the solution?
What tools will you use to evaluate its accessibility?
e. Operational considerations
Does this solution cause adverse aftereffects?
How will data be recovered in case of failure?
How will the solution recover in case of a failure?
How will operational costs be kept low while delivering increased value to the users?
f. Risks
What risks are being undertaken with this solution?
Are there risks that once taken can’t be walked back?
What is the cost-benefit analysis of taking these risks?
5. Deliberation
a. Discussion
Elements of the solution that members of the team do not agree on and need to be
debated further to reach a consensus.
b. Open Questions
Questions about things you do not know the answers to or are unsure that you pose to the
team and stakeholders for their input. These may include aspects of the problem you
don’t know how to resolve yet.
8. References and Acks
Links to documents and resources that you used when coming up with your design and
wish to credit.
Credit people who have contributed to the design that you wish to recognize.
This template is based on the following public article
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-
specs/ with some changes and added notes made by Dr. da Silva.
Last update: 10/21/2020
Questions? Reach out to the instructor on Slack, by email, or during office hours.
