Design Deliverables — Who Builds From What
In one line
The readers of design deliverables are developers, and the purpose is one thing — to let them write code without asking again. If questions come back up, that deliverable has failed.
Why this is needed
The moment you treat a design document as a formality, the project stalls at the development stage. When the deliverables are poor, developers have to ask the planner every time, the planner gets the same question twenty times a day, and the answers are scattered across a messenger rather than a document. When a new developer joins two months later, there is no way to read that messenger.
The bigger problem is that simultaneous work becomes impossible. For a screen developer and a backend developer to share one screen, both must be looking at the same specification, and without a specification one waits for the other. The real purpose of deliverables is not record-keeping but parallelization.
Design deliverables are 'specifications sent to developers'
When the analysis phase ends, you move to the design phase. The reader of this phase's deliverables is the developer, and there is only one purpose — to let the developer write code without asking the planner again. If questions come back up, that deliverable has failed.
The ones actually used in the field are roughly these five.
| Deliverable | Reader | What happens without it |
|---|---|---|
| Menu structure diagram | Everyone | The screen ID scheme differs from person to person |
| Screen definition document | Screen developers, publishers, QA | They ask about the behavior of every single button |
| ERD / table definition document | Backend, DBA | Column types and lengths are set differently by each developer |
| Interface definition document | Developers of both systems | You lose a whole day on the first day of integration testing |
| Program list | PL, QA | With no unit to count, progress is reported by gut feeling |
The screen definition document — the 'behavior', not the picture, is the substance
If you look at a screen definition document made by a newcomer, it has a large screen capture pasted in. What developers really need is the table that should be under the picture.
- Item definition: item name / required or not / input format / maximum length / initial value / code reference
- Event definition: when which button is pressed → what validation is done → where it goes
- Error handling: the message when validation fails, the message on a server error
- Permissions: who can see this screen, and which buttons are disabled for whom
In particular, a screen definition document without permissions will certainly cause an incident in integration testing. A defect like "a button that should be visible only to administrators is visible to ordinary users" gets more expensive the later it is found.
The table definition document — standard words come first
Public-sector projects have the "Guidelines for Database Standardization of Public Institutions", and most large private companies also have an in-house data standard. The order is this.
표준단어사전 (주문 → ORD, 고객 → CUST, 명칭 → NM, 일자 → DT, 금액 → AMT)
↓
표준도메인 (금액 → NUMBER(15,2), 일자 → CHAR(8), 여부 → CHAR(1) Y/N)
↓
표준용어 (주문금액 → ORD_AMT, 고객명 → CUST_NM)
↓
테이블정의서 (ORD_AMT NUMBER(15,2) NOT NULL DEFAULT 0)
If you follow this order, even in tables made by different teams CUST_NM is always the customer name
and always the same length. If you don't, CUST_NAME, CUSTOMER_NM and CUST_NM coexist in one DB,
and you pay for it three years later during data migration.
The practice of using a single-character Y/N for flag columns and CHAR(8) YYYYMMDD for dates is still
common. You may not like it, but if you have to integrate with legacy systems that were already built that way,
making only the new tables different costs more. A standard is not 'the best' but 'an agreement'.
The interface definition document — the document with the most incidents
In system-to-system integration, the two sides are different companies, with different developers, and different test schedules. So anything not written in the definition document is implemented differently by the two sides, 100% of the time.
What must be written:
- Interface ID, business name, sending/receiving system, integration method (REST/file/queue/DB link)
- Frequency (real-time/daily batch/hourly batch) and time, and the reprocessing rules
- Message layout: item name / type / length / required / sample value / remarks
- Character set (UTF-8? EUC-KR?), date format, number of decimal places for amounts, sign representation
- The response code scheme and the receiving side's action for each code (retry/stop/notify the owner)
- Contact procedure and SLA in case of failure
If just these two, character set and date format, are not written down, the first day of integration testing is lost. There is a saying in the field: "What is not in the interface definition document is surely implemented differently."
The real purpose of design deliverables is 'simultaneous work'
If you ask why so many documents are written, the answer is parallelization. An SI project has dozens of people and a fixed schedule. For screen developers, API developers, DBAs and integration owners to work at the same time without waiting for each other, the "agreed interface" between them must exist as a document.
Agile teams can cut down on documents because they talk every day in the same room. In SI the companies differ, the floors differ, and even the networks are separated. Under those conditions documents are not bureaucracy but a synchronization protocol.
What to actually look at when reviewing deliverables
Catching typos in a review meeting is a waste of time. What you should look at is this.
- Is the requirement ID attached (is it traceable)?
- Are there numbers (length, count, frequency, timeout)?
- Is there an exception flow (a design document with only the normal flow is half a document)?
- Has the other side signed (the interface definition document is a document of agreement between both sides)?
What you see in the field
The first thing to collapse when a design document is poor is the first day of integration testing.
If field lengths or required-or-not are blank in the interface definition document, the developers on both sides each build from a reasonable guess. Then in the first integration test the messages don't match. That day goes entirely to negotiation rather than development, and the result of the negotiation usually stays in a messenger rather than in the definition document — so two months later the same problem happens again.
In a screen definition document it shows up differently. If only a large picture is pasted in and there is no behavior table, the developer asks the planner about every single button. On a day when the planner is away, that screen stalls. Without deliverables, people become the bottleneck.
So what to look at in a deliverable review is not how smooth the sentences are but just one thing: "Can a developer write this alone by looking at it?"