We use the tech requirements document as a single source of truth when it comes to the scope and goals of a tech roadmap item.
This sample is based on a combination of templates from Atlassian. This does not include the actual proposal of architecture changes, key decisions, approvals and reviews, etc. It’s just focused on laying out what needs to be achieved. Normally we have other documents specific to the design and decisions and everything will just get linked together in a parent roadmap item.
Template and key data
Overview
Explain why we are doing this.
If it’s a problem to be fixed, describe the main issue.
If it’s an opportunity like a new tech to be adopted, describe what it does.
Impact
How does this affect the overall business goals? the tech group-wide goals?
Impact statements should be short but clear. Numbers are appealing.
Add supporting evidences so the audience will know that this is based on data (e.g. incident tickets, graphs, reports)
Goals and success metrics
How do we know if we have achieved the objectives?
This should also be based on data. Will this be a manual extraction or do we have available monitoring systems, dashboards, and reports platforms?
Requirements
High-level only. Consult with other stakeholders and approvers to make sure everything is covered.
- For example, review this with teams in product, business, security, compliance, data privacy, legal, marketing and so on. It depends on the scope and nature of the initiative.
For prioritization, we can also do t-shirt sizing instead of man-hours.
Quick rules that we use:
“Low” can be deferred; affects immediate team only
“Medium” for important but not urgent items
“High” for critical and urgent items like security fixes or those tied to a hard deadline
“Blocker” is for an item that is a hard dependency of another initiative
Challenges
Any concerns that may affect the roadmap (e.g. lack of data, no budget, missing headcount)
These are helpful to understand why an important roadmap item may not be pushed for a higher priority. For example, this feature has great expected impact, but this will require a big budget to cover all of the additional infra costs. Or simply because there are way more important and urgent matters.
Next steps
- The action items. This can be a high-level list or a Jira macro embed of the related tickets or a link to Atlas
References
- Additional supporting documentation, including but not limited to attachments of full reports, links to related work in other teams or external links
Requirement types and details
We have Functional Requirements that define what the system should do, and Non-Functional Requirements (NFRs) that define how the system should behave. Let’s focus on the NFRs as many times, these are overlooked or have become afterthoughts.
Common Topics For Non-Functional Requirements
These are in the form of questions but the actual requirements should be clear statements that will address these.
Architecture & Scalability
How much traffic are we expecting?
Are we expecting a marketing campaign that will create a spike in traffic?
Are we expecting more clients to be onboarded soon?
Observability & Monitoring
Do we need to add alerts or notifications especially for critical transactions?
Do we have distributed tracing?
Do we have end-to-end analytics tools?
Do we have dashboards to easily visualize the application’s health?
Traceability & Auditability
Do we have reference numbers for all transactions?
How easy is it to trace logs?
Can we see the full user journey? Do we know where users drop off?
Do we have audit logs?
Data Privacy & Security
Are we handling personally-identifiable information (PII) properly?
What kind of data are we collecting and how do we handle them in transit and at rest?
Do we encrypt, mask or obfuscate sensitive information?
Are we following the standards for cardholder data according to PCIDSS?
Do we need geo-blocking for certain countries?
Do we need GDPR notices?
Performance & Reliability
Have we defined the target Service Level Objective?
Do we have any Service Level Agreements with third-parties that we need to take into account?
Do we have failover mechanisms?
Can we handle DDOS attacks?
Operationalization
Is this fully automated or does this need manual processes?
Can we handle toggling on/off at the feature-level? Or will we always need a full rollback?
Do we need beta testing before going public fully? Do we have the ability to target user segments?
How easy is it to create reports?
Tech - (e.g. application’s health, infra, transactions, incidents metrics, etc)
Product and Business - (e.g. user journeys, feature adoption rate, conversion rate, etc)
If a user asks for help or submits a complaint, how easy is it to investigate the issue? Is our level-1 support team enabled to trace and do simple fixes, or do they always need to go to level-2 support?
Maintainability & Extensibility
Is this going to be built on top of a legacy service?
Is this going to need a new tech stack?
Will this be designed as a platform-as-a-service?
Compliance & Regulatory
Are we compliant to <insert international standards>?
Are there any <laws, local regulations> that we may need to review?
Learnings
Know your audience. If you are going to pitch to Business, show something more attuned to the financials. If Product, maybe metrics like number of active users or adoption rate. If fellow Tech, then the effects on reliability, maintainability, etc.
- For Tech, it should be aligned to Business so there will still be numbers involved. Like potential savings on infra costs.
Be honest about the challenges, even if it means writing down unfamiliarity with the tech stack or something similar. These should be a part of the retrospective so that they can be addressed properly.
If the initiative is too big, I usually draft the MVP only or at least indicate the expected phasing.
During data gathering phase, consultations with key stakeholders and final approvers should be done as early as possible. For example, if the changes require handling user’s sensitive information, the data privacy team should be able to give their own requirements (e.g. proper storage, masking/obfuscation, etc)
Sometimes we add the assessments needed as a separate roadmap item. The result with be the completed tech requirements document up to approval of proposed solution. The actual implementation can be another roadmap item.