1. LandOffer
  2. Blog
  3. All articles
  4. Write a Technical Design Document Before Implementation Becomes the Default

Onboarding & Teamwork

Write a Technical Design Document Before Implementation Becomes the Default

A fictional notification-service proposal and completed review revision show how to document trade-offs before implementation fixes the direction.

9 min readLandOffer team

Write a technical design document while the important choices can still change. Explain the problem, the constraints, the proposed behavior, the alternatives you rejected, and the questions reviewers must resolve. Share that argument before implementation effort turns an untested preference into the easiest path to keep following.

A design document can start small and evolve alongside a prototype. It exposes the reasoning behind a choice and the conditions that would change it. This guide from LandOffer uses a fictional notification-service proposal and a completed review revision. The people, dates, requirements, and decisions are editorial examples; no service was built, benchmarked, or security-tested.

A drafting board holds movable architecture models beside an unattached foundation block, keeping a design choice open before construction.

Decide which question deserves a design document

Use a design document when a technical choice has consequences that a task description cannot adequately explain. A new stored-data boundary, a change in service ownership, or a dependency on another team's authorization behavior deserves more discussion than an implementation checklist. Name the consequential decision before selecting a technology to implement it.

An agreed work brief establishes what someone needs and what counts as completing the assignment. A technical design document explains how a system should behave and why that approach fits the constraints. Code review then examines the implementation. These artifacts can inform one another, but approval of a brief does not establish architectural suitability, and an approved design does not establish that code implements it correctly.

In his July 2020 account, Malte Ubl describes design documents at Google through context, goals and non-goals, design, alternatives, and cross-cutting considerations. Treat that account as a useful historical perspective, not a statement of every team's current process. Adopt sections that expose your decision; do not borrow an employer's name as a substitute for reasoning.

For a small, familiar change, a short proposal in the team's existing work record may suffice. For a consequential change, a longer document may be warranted. Length is a consequence of the decision's complexity. It is not evidence that the proposal is ready.

Build the argument around behavior and constraints

Open with the situation that requires a choice. Describe the current behavior, who experiences the problem, and what you actually know. Separate measured conditions from stakeholder requests and working assumptions. A request for fewer missed reviews, for example, does not establish that reminders will improve completion rates.

Then make the boundary concrete. Which users, records, channels, and failure cases are included? What remains outside the proposal? A non-goal should prevent an understandable expansion of scope, such as adding email delivery to an in-app reminder. Required security and accessibility responsibilities still apply within the chosen scope.

Explain the proposed path through the system in words before adding detailed interfaces. Identify what information is stored, when it is read, and which component decides whether a user may see it. Reviewers need enough detail to challenge those boundaries. They do not need invented API signatures that distract from an unresolved design choice.

Finally, state what would make you choose something else. Useful alternatives share the same problem and constraints. Comparing a modest scheduled job with an elaborate unrelated platform makes the preferred option look stronger without testing its merits. Include the current approach when retaining it remains a reasonable choice.

Worked design: an internal review reminder

The following is a completed first proposal, dated November 2, 2026, for an imaginary research-review portal. All conditions are stipulated for the example. Mira, the author, asks the team's decision owner, Petra, to choose a direction for exploration. The record is a proposal, not permission to release.

Context and problem. Researchers use an existing pending-reviews page to find assignments. Product colleagues report that some reviewers forget to open it. There is no measured baseline for missed assignments or reminder effectiveness. The immediate request is a discoverable in-app reminder, not a demonstrated improvement in review completion.

Goals. Make the pending-reviews destination easier to find after sign-in; preserve existing access restrictions; and keep the first increment within the portal team's operational ownership. The design must account for assignments being completed, reassigned, or made inaccessible after a reminder is prepared.

Non-goals. No email, push delivery, automatic reassignment, ranking of researchers, or claim that a reminder proves someone read an assignment. The proposal does not redesign the portal's authorization system. Dependence on that system remains a design risk to investigate.

Initial proposal, version 1. Once daily, a portal-owned scheduled job would create a reminder record for each reviewer with pending work. That record would contain the assignment titles and a count from the job's snapshot. After sign-in, the portal would display the saved reminder and link to pending reviews. Completing an assignment would change the underlying assignment record; the daily reminder might remain stale until its next refresh.

Reason for this preference. A daily job appears to match the proposed cadence and would avoid introducing a separate event-processing service. This is a maintenance judgment under the fictional team's constraints, not a verified comparison of cost, reliability, or speed. Version 1 has not yet justified storing restricted titles outside the existing page.

Alternative Why it is plausible here Consequence to examine
Keep the existing page without a reminder Adds no new notification state or processing Does not address the reported discoverability problem; the team could first investigate that report
Emit a notification for each assignment event Could represent assignment creation and later changes individually Requires deciding how completion, reassignment, and access changes affect existing notifications
Show a generic reminder linking to the current pending-reviews page Avoids copying assignment details into the reminder Depends on the destination enforcing current access and handling an empty or unavailable result

Unknowns and review request. Does the existing page check authorization on each relevant request, and how are cached results invalidated? What happens after permission revocation? Is the daily job necessary if the reminder contains no assignment-specific information? What operational burden would the new job introduce? Mira asks reviewers to challenge the stored-data boundary and cadence before the team commits to version 1.

Proposed feasibility work. First inspect the existing authorization and caching behavior in an appropriate development environment. Then explore a generic reminder without restricted content. Include completion, reassignment, permission revocation, empty results, and destination failure in the exploration plan. These are planned checks, not completed experiments, and no response-time target has yet been agreed.

The proposal makes a preference visible, but it also exposes a weakness in that preference. Storing titles is convenient for display; convenience alone does not justify an additional place where restricted information could persist. That is a productive review question while the representation is still cheap to change.

Let review change the design, then record the decision

A crossed-out detail plaque becomes a generic Review assignments link pointing toward an archive doorway; a tag keeps checks visibly open.

Make it easy for reviewers to challenge a meaningful part of the proposal before the team invests in it. Ask specific questions of people with relevant knowledge: the authorization boundary for a security reviewer, job ownership for operations, and useful behavior for the product owner. A broad request to approve the document makes it harder to tell whether those concerns were examined.

GitLab's published architecture workflow describes documenting decision context, benefits, trade-offs, alternatives, and the reason for a choice. It also allows design and exploration to evolve together. That supports making uncertainty explicit; it does not make GitLab's roles or approval rules binding on another organization.

Here is the completed fictional review record for the reminder proposal:

Review contribution Author's substantive revision Remaining consequence
Soren, security reviewer: a user could lose access after the daily snapshot, while the reminder still exposes a title Remove titles and counts from reminder content; link to the existing access-controlled destination The destination's authorization and cache behavior still require verification
Inez, operations reviewer: a daily job creates monitoring and ownership work without a demonstrated need for saved reminder state Replace the scheduled record with a generic reminder shown during the signed-in portal experience The team must define when it appears and how dismissal behaves
Petra, decision owner: do not assume reminders increase completed reviews Keep effectiveness as an unanswered product question; separate behavioral feasibility from later outcome evaluation No delivery or performance benefit is claimed

Revised design, version 2, November 4. The portal would display a generic “Review assignments” link after sign-in. It would contain no titles, counts, or assertion that the user currently has pending work. The destination is intended to retrieve only assignments the user is presently allowed to see; the exploration must verify that behavior. An empty result would explain that no accessible pending reviews are available; it would not reveal formerly accessible titles.

Decision recorded by Petra. Proceed with a development-only exploration of version 2. Do not implement the scheduled snapshot design. Mira owns the exploration record; Soren owns review of the authorization findings; Inez reviews failure handling and operational ownership. Revisit the direction on November 9 with evidence about permission changes, caching, empty results, and destination failure. Production release remains undecided and requires the team's normal approvals.

Unresolved choice. Whether the generic reminder can be dismissed, and for how long, remains open. Mira will bring two behavior sketches to the next review. Neither dismissal persistence nor an additional stored-data design is implicitly approved by this decision.

This is a real revision within a fictional case: the team removes the daily job and changes the information representation. It does not merely add a security paragraph to the original plan. The record preserves why version 1 was rejected, what version 2 permits the team to explore, and what evidence is still missing.

Keep proposals, evidence, and release status separate

A design document needs visible status because readers arrive at different times. Put the author, version, decision owner, review request, and current decision near the beginning. Link the review record from the proposal. If a decision is superseded, retain its rationale and point to the replacement so an old discussion cannot silently become current guidance.

During exploration, record findings with their boundaries. A development check of a particular permission-change sequence would support a statement about that sequence in that environment. It would not prove all authorization paths are safe. A timing measurement would need its workload, environment, method, and limitations before it could support a performance claim. In this article, there are no such results.

Keep failure behavior concrete even before testing. In the example, a generic reminder must not suggest that work is overdue when the destination is unavailable. The design should specify an unavailable-state message and the responsible operational owner. Whether the implementation satisfies that behavior belongs in subsequent verification, not in a confident adjective in the proposal.

Google's documentation best practices distinguish a design document's proposal and feedback role from its later value as a record of decisions. Maintain current operational instructions where the team expects to find them. An archived design explains why a choice was made; it may no longer describe the deployed system accurately.

Before sharing your next proposal, identify the choice reviewers can still change, write the strongest plausible alternative, and name the evidence needed for the next decision. Use LandOffer's other career guides for broader workplace topics, then return to your team's actual design and review process. The useful next step is a reviewable argument with an explicit decision request.

Sources and Further Reading