found during implementation → Re-implement almost from scratch Each pull-request looks good → The codebase itself gets hard to read These problems can be solved though design docs
separate document (PRD) if required - Use PRD to discuss whether it is worth implementing Make the scope clear - Create sections of “out-of-scope” or “future plan” if required
Reasons for and benefits of the implementation/refactoring - Terminology and technical background - Prioritization: Scalability, robustness, performance…
important issue - “We use LRU with adaptive size for dynamic demand…” - “Backward dynamic references are resolved by SeviceLocator” - “Here, layer A is split from B to minimize…"
sufficient sections - Section of objective/goal is almost required - Use external document if possible Top-down approach - Objective → background - Design overview → details
with… - A small group: e.g., only with a tech-lead - No concrete idea: Find it during the discussion - Almost blank document: Minutes can be a good draft