Before building an ML system, write down what problem it should solve and why the proposed approach is worth trying. A design document is a working specification: it aligns builders and stakeholders on goals, priorities, and design decisions. It can also reveal that a simpler solution—or no ML project—is the better choice. section 4.0 section 4.1.4
Keep the document proportional to the project, but make its decisions testable:
- State the problem, goals, and stakeholders. Name antigoals—areas the project should avoid—so additions do not quietly change its purpose. section 4.0 section 4.6
- Ask whether the result is achievable, what resources it needs, and whether a lower-effort approach would deliver enough value. section 4.1.4
- Record system-specific choices, including features when predictions depend on them. Use a minimal structure and extend it where the system needs detail; do not treat a template as a checklist to fill blindly. section 4.1.3 section 11.5
Retail demand forecasting
A retail chain planning a demand forecast can begin its specification with the business problem and its origin, then add design decisions as they become clear. The aim is not to produce every implementation detail on day one; it is to give stakeholders a shared account of what is being proposed and why. section 4.3 section 16.3
Circulate the draft where reviewers can find and navigate it. Ask people with different expertise to challenge assumptions and propose alternatives. When feedback favors a technology, investigate the reason: infrastructure limits, maintenance capacity, and the proposed system flow may matter more than preference. “Looks good to me” is less useful than a specific objection or confirmation. section 4.4 section 4.6
Revise the specification through review and after launch. Production flaws, new features, legislation, or infrastructure changes can invalidate earlier decisions. Keep the overview current so later maintainers can understand the system; use separate guides, API documentation, and operational documents for detail it is not meant to hold. section 4.5 section 16.3
