I whipped up a design doc template recently and thought someone else out there might find it to be a useful starting point. For me, I find a lightweight design doc (1-4 pages) to be a really useful way to focus your thinking before diving too far into the code. I’m not a fan of heavy rigid design docs as they typically cause you to waste time writing (or copying …. ugh) stuff that no one will read.
The doc structure should force you to do some of the thinking you’ve been putting off. Then you can do a quick review of that with whoever serves as a stakeholder (customers, product mgmt, etc). At that point, I’m happy to abandon the doc or go through another update cycle, depends on the context. I don’t think it’s worth keeping the doc perfectly in sync with the code after the thinking and understanding phase starts to die down.
Here’s the doc: