Scribd
Upload
55 views5 pages

Front Matter: A. Overview, Problem Description, Summary, or Abstract

The document outlines a template for writing technical specifications with sections including an introduction describing the problem and goals, current and proposed solutions, considerations, and a discussion section. The introduction would summarize the context of the problem, goals of the product, and requirements. The solutions section would describe the current approach, a proposed new design, and alternative designs considered. Further considerations may address security, privacy, accessibility and other factors. A deliberation section allows for discussing any areas of disagreement or open questions regarding the solution.

Uploaded by

Bob
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd
55 views5 pages

Front Matter: A. Overview, Problem Description, Summary, or Abstract

The document outlines a template for writing technical specifications with sections including an introduction describing the problem and goals, current and proposed solutions, considerations, and a discussion section. The introduction would summarize the context of the problem, goals of the product, and requirements. The solutions section would describe the current approach, a proposed new design, and alternative designs considered. Further considerations may address security, privacy, accessibility and other factors. A deliberation section allows for discussing any areas of disagreement or open questions regarding the solution.

Uploaded by

Bob
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd
You are on page 1/ 5

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.

You might also like