Refactoring English sets out a practical framework for software design documents
The guidance recommends tailoring design documents to a project’s complexity and risk, with particular focus on costly or difficult-to-reverse decisions.
Refactoring English has published guidance on writing effective software design documents, arguing that the process helps teams examine major decisions before implementation and coordinate with colleagues and partner teams.
The article says design documents can range from a one-page outline to a lengthy document requiring approval from multiple teams. The appropriate level of detail should reflect a project’s complexity, risk, deadlines, goals and working culture. In some cases, it says, no design document may be necessary.
A central principle is to prioritise decisions where the cost of being wrong is high or the choice would be difficult to change later. The guidance contrasts durable decisions, such as programming languages and storage systems, with minor product choices that can be changed quickly in response to user feedback.
Suggested sections include the project’s objective, background, goals, non-goals, scenarios, architecture, constraints, dependencies and service-level objectives. The article also recommends documenting monitoring, timelines, security, privacy, legal considerations, logging, unresolved issues and alternatives where they are relevant.
Refactoring English advises using editable diagrams, measurable performance objectives and concise explanations of rejected alternatives. The author says they have written design documents at Google, Microsoft and their own companies, while the examples in the article are presented as illustrative guidance rather than a formal standard or empirical study.
