Technical specifications serve as a blueprint that outlines the requirements, functionality, and design of a system or product. In this blog post, we share the technical specifications template we use internally for our development process.
As a company in the Atlassian Marketplace, our development team regularly gets feature/ product update requests from the product and marketing teams. A number of times these requests lacked clarity as to the end goal, the product’s functional requirements and use cases
To solve this problem, our development team created our technical specifications template as a key part of our internal development workflow. The development team uses it to collect product and feature requirements before starting a development sprint.
Table Of Content
- Metadata
- Objectives / Scopes
- High-level non-functional requirements
- Timeline, sequences and dependencies
- Diagrams
- API
- Security
- Storage
- Schema changes
- Queries we should be able to handle
- Security
- Data migration
- 3rd parties
- Security
- User experience
- Analytics
- Testing strategy
- Deployment strategy
- Release strategy
- Clean up tasks
- Questions / Risks
- Additional links
Write the technical specifications as if you are writing it for somebody else and it will be done without your presence.
Metadata
Jira issue(s)/Product specs
Creator/Owner
Reviewers
Applications involved
People involved: Designers, PMs, Engineers, etc
Objectives / Scopes
Define the objective of this change. Very high-level technical goals
High-level non-functional requirements
List the requirements you believe are important to write down to make the assumptions obvious. You can consider logging, performance, scaling, etc.
Timeline, sequences and dependencies
The timeline of the delivery of this change.
Diagrams
Solution architecture and other diagrams that help communicate the change, the current or future situations.
API
New and existing API contract updates in TypeScript. Pay attention to names and types and forward compatibility.
Security
- Which permissions/scopes are required for each endpoint
- How do we not leak the tenant’s data
Storage
Schema changes
TypeScript-like schema of tables and indexes.
Names are well-defined.
Queries we should be able to handle
Required queries are listed and shown how each query is satisfied and which indexes it hits.
Security
- Point-in-time recovery set
- Critical fields are encrypted
Data migration
Data migrations steps outlines, software pieces lists, steps listed.
3rd parties
Which 3rd party APIs / integrations are involved. What is required to call those? How do we use the data, when we call them and what we store in our systems?
Security
How do we use the accessed data? How do we use the data and access credentials?
User experience
- References do design, how do we split into components, how to we re-use components.
- How do we do error handling?
- How do we help the customer to debug? How do we handle errors?
- Any security considerations?
- How do we integrate with 3rd parties?
Analytics
Which analytics events are implemented
Testing strategy
- Which use cases are going to be covered by autotests?
- Explain how this project will be tested and which loom videos will be recorded
- Consider different browsers, environments, mobile vs desktop, huge customers, etc
- Which instances will be used for testing
- Is penetration testing necessary?
- Who reviewed the OWASP Top 10 for this change?
Deployment strategy
- Do we need to do anything special here?
- Is there any data loss risk?
- Do we have any manual steps?
- How do we test this?
Release strategy
- Do we do all-in, opt-in, and experiment rollout?
- How do we validate the success?
Clean up tasks
- Do we need to do any infra clean-up? Personal / Dev stages?
Questions / Risks
List the main risks and questions which you cannot answer yet.
Additional links
Any Internal or External links that are helpful.
This template, specifically designed for documenting technical specifications, enables teams to create clear and comprehensive blueprints for their systems or products. By utilizing this template within the collaborative environment of Confluence, teams can enhance communication, streamline the development process, and ensure accuracy in capturing requirements, functionality, and design aspects. We hope you find this helpful.
