Passing Acceptance Isn't About More Documents—It's About Decision Ownership

Why Complete Documentation Still Fails Acceptance

A ten-month project demonstrates the core problem: at acceptance, the client cites requirement 4.2 requiring manual posting for failed corporate payments within two business days. The project manager presents a full set of documents—project plan, risk list, requirements specification, high-level design, detailed design, database design, interface specification, security design, test plan, test cases, test report, user manual, deployment manual, version notes—all neatly organized and naming-compliant. Yet the documents contradict each other: the specification mandates manual posting, the detailed design marks it "phase two," the test report lacks corresponding test cases, the user manual omits the flow, and the production code only supports retry, not manual posting. When asked if all requirements are done, the team can only say "should be done, we'll verify." Adding more documents (process records, review minutes, implementation notes) doesn't fix the mismatch.

The real issue isn't too few documents—it's that current, valid documents lack owners, versions, and decision traceability. Expired and current documents mixed in the same directory look like a complete system but function like none.

Documents Answer Questions, Not Just Fill Templates

In traditional projects, documents are contractual deliverables read by clients, supervisors, auditors, on-site ops, and trainers—not just developer notes. A delivery checklist easily becomes a fill-in-the-blank exercise. The key is remembering what question each document answers. Before code, over a dozen decisions must be recorded; otherwise they hide in someone's head and vanish when that person is absent.

Documents aren't for review signatures. They're for yourself three months later, the next hire, and the client holding the contract at acceptance.

Two Document Types: State vs. Decision

Traditional projects treat all Word files the same: all controlled, all signed, all archived. Result: documents that should be frozen aren't, documents that should evolve with code can't change, and obsolete documents remain marked "current."

State documents describe "what it is now": interface paths, fields, table structures, config items, deployment commands, user manual steps. They expire when code changes. Keeping expired state documents as current is worse than having none—people confidently follow them and do the wrong thing.

Decision documents record "why we chose this": why manual posting instead of auto-reversal, why amounts in cents not decimals, why file-based reconciliation instead of real-time interface. Code and comments can't capture this. Post-hoc decisions are often sanitized history. The industry calls these ADRs (Architecture Decision Records); you can name them "Architecture Decision Specifications" or "Major Technical Decision Records," typically 200–500 words. When state changes, don't rewrite history—write a new decision, declare the old one superseded, mark the old file "obsolete."

Configuration management must answer three questions on the spot: which program package is running in production? Which versions of specification, interface, and user manual correspond? When was the previous version obsoleted? If you can't answer, you have an archive, not a system.

Expired documents are more dangerous than missing ones. Missing docs force people to read code and ask; expired docs let people confidently do the wrong thing with "controlled files."

Three Document Pairs That Most Often Break Acceptance

Business Requirements vs. Requirements Specification

Business requirements answer: who wants what result in what scenario. Audience: business, client reps, trainers, testers (high-level). Example: "As a finance clerk, I want to initiate manual posting after payment failure so that when the bank has deducted but the system hasn't recorded, I can reconcile and produce a reconciliation statement within two business days." It should NOT specify table design, API calls, or state machines.

Requirements specification answers: what precise conditions the system must meet, boundaries, exception handling. Audience: developers, testers, architects, client, supervisors, acceptance team. Rules must be verifiable: "Only when payment instruction status is FAILURE or UNKNOWN and bank reconciliation file confirms deduction, allow manual posting. Amount must equal original instruction amount, precise to cents. Same instruction can be posted at most once. Reconciliation statement generated within two business days after successful posting, containing original instruction number, bank serial, posting time, operator. Unauthorized users receive PERMISSION_DENIED, no posting record created."

Business requirements are user perspective; specification is system perspective. Experience says "reconcile ASAP"; specification must define two business days, once, to the cent, who can do it.

IEEE 830 and its successor ISO/IEC/IEEE 29148 emphasize verifiability. Vague "support posting" is not a requirement and won't hold in contract. Many reworks stem not from developer ability but from merging these two into a "four-not-like" document. Business thinks it's clear, developers implement their understanding, testers write cases from a third understanding, and at acceptance the client asks spec clause 4.2 line by line—nobody can answer fully.

In traditional projects, specification is the contractual baseline. Changing it requires a change request; you can't just say in WeChat "do auto-retry first, posting in phase two." User manual matches specification rules, not the project manager's verbal "roughly that meaning."

High-Level Design vs. Detailed Design

High-level design views the map: how the system splits into modules, what each does, how it connects to client systems, banks, internal core. Granularity stops at module/subsystem level, not method implementation details. For manual posting, it might reside in "Reconciliation Service," decomposed into failure detection, posting application, approval, entry, statement generation. External dependencies: payment gateway, core accounting, file reconciliation, permissions. Key decisions recorded here: why UNKNOWN status can't auto-post, why manual approval required, why reconciliation statement can't live only in logs.

Detailed design views the navigation: classes, methods, state machines, exceptions, key algorithms. Developers code against it; testers write cases from it. But detailed design isn't a contract attachment to read page-by-page with the client. Printing 100 pages of method descriptions for the client helps neither review nor maintenance.

State machines in detailed design are the most critical diagrams and the easiest for testers and clients to align on.

High-level design reads the map; detailed design reads the navigation. If a review meeting debates whether to split the reconciliation service while someone else argues whether a method should throw an exception, the two layers are conflated.

In traditional projects, high-level design is the main document for cross-team and client technical reviews. Database schemas and interfaces often need separate volumes because DBAs, testers, external vendors, and client interface owners don't read code. Security design is mandatory: who can initiate posting, can frontend tamper amounts, audit logs, bank return verification—required for security compliance and acceptance.

The sequence "high-level design approved, then detailed design, then mass coding" isn't dogma; it's because downstream partners await frozen boundaries. Unfrozen boundaries mean interface changes three times, vendor changes three times, test reports invalidated three times.

Detailed design can be trimmed by module. Core accounting, posting, reconciliation, external interfaces deserve state machines and key methods. Ordinary query and config pages can rely on code, unit tests, and schema descriptions—no need to write unread manuals just for a complete directory.

Interface Specification vs. Internal Implementation

Interface specification is the external contract: what external systems (client, bank, counter, vendors) send, receive, error handling. Version numbers, change logs, compatibility strategies required. When integrating externally, this document approaches contract attachment status.

Internal implementation is your own business: method steps, transaction control, retry counts. Implementation can refactor; external contract cannot be silently changed under "optimization."

Idempotency belongs in the contract: duplicate posting for same instruction returns existing posting record, no second creation. Error codes are also contract: PERMISSION_DENIED, AMOUNT_MISMATCH, DUPLICATE_APPLY —external systems must handle them per the same table.

Handwritten interface specs are fine but must update with implementation and go through configuration library versioning. Field changed but doc not updated leads to the embarrassing "your doc is 1.2, code is 1.4" at integration. Field tables generatable from code or interface definitions should not be manually copied into Word—each copy adds a rotting state document.

Test Documents and Manuals Are Acceptance Evidence, Not Closing Tasks

Requirements specification states "what we must do." Test documents and user manuals prove "we did it, and others can use it per current version."

Test plan must define exit criteria. Without them, testing becomes "click around," release becomes "feels okay," acceptance becomes "let client try."

Test cases need preconditions, steps, expected results. Expected results can't just say "interface returns success"; must specify: posting status becomes POSTING, core accounting adds an entry, reconciliation statement PDF queryable within two business days. P0 cases block acceptance; P2 can go to backlog.

The Requirements Traceability Matrix (RTM) is the one traditional project document you must not skip. It links each spec clause to design, code module, test case, test result, and current program version. The article provides an example matrix with rows for REQ-042 through REQ-045 showing module, test case, result, and build version. Notably REQ-044 (two-day reconciliation statement) fails and is marked "not included in this version."

When the client asks "is everything done?", you can answer clause by clause. Without this matrix, you can only say "should be done." The failed REQ-044 must be explicit: this version lacks acceptance criteria for that clause—either extend schedule or raise a change request to remove it from scope. Ambiguity guarantees on-site failure.

Test report cover must state: defect density, P0/P1 clearance, residual risks, acceptance recommendation. Writing "basically passed, details later optimized" equals writing nothing.

User manual must match live behavior, not the initiation draft. If trainers teach finance clerks to use a posting button that doesn't exist in production, it's not a training issue—it's a state document that didn't follow the version.

QA and configuration managers aren't just helpers. QA asks: did the process happen per agreement—reviews done, changes closed, testing met exit criteria? Configuration managers ask: do artifacts match versions? Without these roles, the team's "completed" has no independent verification.

Real Changes Must Traverse the Entire Document Chain

The most common traditional project accident isn't missing documents—it's mid-project requirement changes while documents stay on the old baseline.

Two weeks before launch, client says: "UNKNOWN status also allows posting, no need to wait for reconciliation file." If only code changes without document sync, the following occurs: tests still write cases for "must have reconciliation file first," interface spec still lists precondition FAILURE, user manual still teaches "wait for reconciliation then post," the architecture decision "UNKNOWN cannot auto-process" is obsolete but not declared obsolete, and at acceptance the client cites the new verbal agreement while the team shields with the old spec—both sides think they have grounds.

A real change must traverse the entire chain, not just modify one interface.

The change request must specify: who proposed, affected requirements, effort impact, which controlled documents change, which version becomes the new current version. A WeChat "just change it" counts for nothing at acceptance or audit.

The risk list entry "requirements change mid-development, probability medium, impact high" corresponds not to "be flexible" but to: change must be assessed, with designated owners for updating spec, design, test cases, user manual, and cutting the new version.

Not writing a risk list doesn't mean no risk—it means you're unprepared when risk hits. Incomplete client interface docs, contested test environments, core developer leave—all can be anticipated and buffered. Writing them doesn't guarantee prevention, but not writing guarantees you're too late.

If the change request stops at the request form, it's merely "applied for"; only when it traverses the chain is it "truly completed."

Contractual Deliverables vs. Internal Merge Candidates

For large traditional software firms, plan, specification, security, test report, user manual, version notes, formal retrospective are often default mandatory items. Rejecting them rejects your basis for dialogue with client and audit.

The real fix: don't write internal collaboration materials and contractual deliverables as the same boilerplate.

Typically contractual/acceptance mandatory:

Requirements specification: without it, acceptance has no ruler.

Architecture or high-level design: without it, technical review has no map.

External interface specification: with vendors or client systems, this nears contract attachment.

Database design: client reviews data, does data handover—must be separate volume.

Security design: security compliance, audit, core transactions default require: privilege escalation, tampering, logs, signature verification.

Test report and traceability matrix: answer "is it done?"

User manual and version notes: answer "how to use this version, which program package?"

Deployment and emergency: on-site ops must execute, not just "establish emergency team, report timely."

Internal merge candidates:

Detailed design method descriptions that map 1:1 with code—merge into code, unit tests, key state machines.

Attachments duplicating interface fields—merge into generatable interface facts.

Process flow water nobody reads—merge into change requests, review minutes, configuration history.

Emergency plans still need timelines. "Report timely after major fault" is insufficient; at minimum: who receives alert at T+0, what logs at T+5, how to degrade at T+10, how to补处理 at T+60, when to notify client. Timeline-less plans are just essays regardless of neat signatures.

Project retrospectives same. Useful retrospectives record only three things: which judgments were wrong, which controlled documents failed at acceptance or incidents, which rule to change next round. "Team collaboration good, launched on time" retrospectives can be omitted.

A Lookup Table, Not a Homework Checklist

The article provides a comprehensive table mapping each document to its answered question, primary audience, contractual/acceptance status, and internal recommendations. (The table is summarized in the text above.)

Reading this table, the impulse is to fill every blank document. Pause and ask the configuration manager:

How many files currently marked "current" in the directory have already been invalidated by code and live behavior but not yet marked obsolete?

If that question can't be answered, adding another document won't save acceptance.

A team that truly passes acceptance doesn't write more documents—it ensures every current document has an owner, a version, and a decision object. Documents nobody uses for acceptance, change, or handover are waste paper.

The Three Disciplines to Adopt

Owner for every controlled document. Specification owned by analyst or requirements lead. Interface by provider. Decision record by deciding architect. User manual by who will train. Emergency plan by ops or on-site. Documents labeled "team collectively maintains" end up collectively ignored. QA spot-checks not prose but whether owner is present and version matches.

Baselines and obsolescence. New version effective, old version must exit current. Detailed design says "phase two," spec says "this version must implement"—both cannot be simultaneously current.

Change requests truly traverse the document chain. Only changing code without updating spec and manual guarantees the "should be done" replay at acceptance. When estimating change effort, include documentation time. Excluding it ensures docs lag, and lagging docs will slap you at acceptance.

Engineers receiving requirements shouldn't dive straight into code. First find three things: architecture or high-level design to locate the feature; database design to locate data; interface specification to understand connections to client, bank, internal core. With the map, then enter code.

When you only see code, you see implementation. When you can point to spec clause, high-level design chapter, interface version, test case, and production program package, you see how the system was designed, controlled, and delivered.

Three years later you'll face the same posting, reconciliation, interface upgrades. The original decision-makers may be gone. Then the team relies not on a cabinet of expired deliverables, nor on "ask old Zhang," but on the few current documents and the living answers behind them.