ข้ามไปยังเนื้อหา

The Technical Requirements Document

เนื้อหานี้ยังไม่มีในภาษาของคุณ

Before I build a solution, I write down how it will be built. On my projects, that’s the technical requirements document, the TRD. It’s one of the first things I start and one of the last things I finish, because it grows with every decision.

This page is the TRD in one place, for every course that uses it. Each SteveTechArc course builds one for SkyOrbita, the solution the courses teach, and you can read them as they grow.

A TRD says what a solution must do and exactly how it’s built: its systems, its data, how the data moves, the rules it follows, and the decisions behind it, including the options that lost and why.

It sits beside other requirements documents, and the names are easy to mix up:

DocumentThe question it answersUsually written by
Business requirements document (BRD)What does the business need, and why?The business, with an analyst
Product requirements document (PRD)What does the product do for the people who use it?A product owner
Technical requirements document (TRD)How is the solution built to meet those needs?The architect, with the team

The BRD and the PRD say what and why. The TRD says how, precisely enough that someone else could build it, review it or change it later without guessing. Every team names these a little differently. What matters is that the how is written down somewhere, and that it’s the architect’s job to make sure it is.

When I teach integration, I start with the system landscape: one box for Salesforce, the other systems around it, and the arrows between them. And I put that landscape in my TRD.

Even the smallest landscape earns its place. Picture a TRD whose landscape is only two boxes: a user’s browser, and Salesforce. No other arrows. That looks too simple to be worth drawing, but it protects you. If someone asks later, “Where’s my mobile app? Where’s the push of my orders?”, the answer is in the document they agreed to: those weren’t in the design. The TRD says what’s in scope, and by leaving things out, it says what isn’t.

It works the other way too. On first calls, when I first talk with a client, I put the landscape up, and memories start to come back. “Oh, wait, there’s another system.” Then another. You’d be surprised how much a simple drawing brings out. Every one of those found on the first call is a surprise you don’t get in month three.

AI can now draft stories, designs and code faster than any team. But AI gives you what you ask for, not what you forget to ask for. If the design document doesn’t contain the constraints, AI won’t honor them consistently.

So the TRD becomes the grounding reference for everything after it: the build, the testing, the review. Besides the functional design, a TRD written for the AI era carries what people used to keep in their heads:

  • the implied requirements nobody wrote down
  • the security assumptions
  • the error-handling approach
  • the integration contracts
  • the scalability assumptions
  • the observability and support model
  • the review gates, and who owns each decision

AI suggests. Architects decide. The TRD is where those decisions are written.

Every SkyOrbita TRD follows one core outline, and the blank template uses the same one:

PartWhat it holds
Front matterCover, document history (every version, what changed and why), contents
1. IntroductionThe purpose of the document, the background
2. ScopeA summary, the deliverables, what’s in and out of scope, assumptions and dependencies
3. Use casesEach capability, numbered, with the business need and what serves it
4. ArchitectureThe technology, the system landscape, the data flow, the entity relationships
5. Data structuresSource to target, reference data, every object, the rules, the source of truth for each piece of data
6. Integrations and data loadsEach way in as numbered steps, each transform step by step, the mappings, error handling
7. Data import, cleanup and reconciliationEvery load checked against the expected counts, and what was cleaned
8. SecurityAccess, and which data is sensitive
9. AutomationFlows, triggers and jobs
10. Naming standardsThe patterns for names, with examples
11. DecisionsEach choice, the options considered and why they lost; the ones that can’t be undone are marked
AppendicesOpen questions (numbered, each with who answers it), references, glossary, the data dictionary

A course adds parts of its own after the core, wherever it teaches something the core doesn’t cover.

The data dictionary is one part of it. Every dataset and every field: what it means, a real example, its type and key, whether it’s sensitive, and what it’s used for. It has its own page, The Data Dictionary, because it’s where the design starts.

The decisions part is the one I’d never skip. Most choices can be changed later, at a cost. Some can’t. In Data 360, for example, a field’s data type is fixed once its data lake object exists (A Data Dictionary Before You Map walks through it). A TRD marks those decisions so that they’re made on purpose, with the whole picture in front of you, before the day you can’t take them back.

The courses don’t hand you a finished TRD on day one. They build it the way a real project does: a little at a time, as each decision is made.

  • One TRD per course, all about SkyOrbita, so together they describe one whole solution.
  • Editions: one for each chapter that adds something, one for each part, and a complete one at the end of the course. Each edition keeps everything from the one before.
  • Versions that don’t change: once an edition is published, it stays as it is. A correction becomes a new version, and the old one stays readable.
  • Built from small files, each holding one fact, and checked against the real data: every name must exist, and every transform is run over the real files and compared with the counts the course gives.
  • Drafted with AI, confirmed by people: an AI drafts each part from the course’s own text and screenshots, citing where every item comes from. The course’s author confirms or edits it. Nothing is guessed: a name the course hasn’t shown yet is marked as a draft, and a difference between the course and the platform becomes a numbered open question.

These course TRDs describe the solution and its data. Deployments, environments and build plans are left out on purpose.

The TRDs live at SkyOrbita Blueprints (opens in a new tab), which also shows how a TRD is made (opens in a new tab).

SkyOrbita Blueprints’ blank templates (opens in a new tab) give you a blank TRD (opens in a new tab) in the same outline, as Markdown or YAML, and a blank data dictionary (opens in a new tab) as a sheet or YAML. They’re dedicated to the public domain (CC0): use them for anything, at work or anywhere else, with no credit needed.

Start small. A purpose, a scope and a two-box landscape on the first day is already a TRD. Add to it with every decision.