Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

I find design docs really useful, even if no one else reads them, because they force me to clarify my thinking before I start the (more expensive) process of implementation.

However, I've also noticed a couple of very common problems with design docs:

- Many design docs don't clearly state the problem that the design is intended to solve. Often the best response to a design is "that problem isn't important to solve", or "there's another system that already solves this problem", or "there's a totally different approach that you should consider", but without a clear statement of the problem and why it's important to solve, it's hard to determine those kinds of things.

- People often focus too much on the details of a design, vs. the important decisions that need(ed) to be made, the alternatives and rationale for those decisions, and the assumptions that they were based on. In a year, you probably won't care that much about the details of the parameters of some API, but you probably will care a lot about why you chose that API over some other one, and it's useful to have a record of that decision.

It's useful to view a design doc as a distillation of the thought process behind a system, vs. a high-level description of how to build something.



Consider applying for YC's Fall 2025 batch! Applications are open till Aug 4

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: