[chartered_stack]

I often come across tips/pointers/exhortations about how to write good design documents. I generally agree that it's an important step: not just for clarifying your own thinking, but also for communicating effectively with others.

However, these types of posts often lack are concrete examples of what a good design document actually looks like. I understand that many of these documents are proprietary and intended for internal use. Still, are there any examples of well-written design documents available publicly that learners can study to get a clearer idea of what one should look like?

[dayjaby]

> However, these types of posts often lack are concrete examples of what a good design document actually looks like

The entire post is an application of his document designing philosophy. It became obvious with his first header being "Goal" and him mentioning to set a goal early on.

[teiferer]

This should grow from within yourself. Read a lot of design docs and blog posts and articles and books. Which ones did you like? Which were confusing? And why was that? Was it the language complexity? Length of explanations? Diagrams? Too much / too little reasoning? Did you feel that the writer did a good job of picking you up were you were and brining it to a new state which now was enriched with their idea?

Constantly ask youself whether you liked a particular piece of writing and that will over time shape your understanding of what's good and what's not. Note that that's not entirely objectively quantifiable and people will have different tastes. That's also why it's hard to have a "good examples" archive because, just like with code, that would immediately people to start debating. But there is a certain core of properties most people can agree on.

[i_don_t_know]

Somewhere in some comment antirez said he writes design documents for his projects before he writes a single line of code. You can browse his GitHub projects or google “antirez design documents” or “antirez specification”.

https://github.com/antirez

[publicola1990]

Yes this is also a question that comes to my mind. Where are the design docs from the past 50 years of software development. There must be something concrete for people to study and learn from.

[dboreham]

I've been doing this stuff for 40 years and spent the first 20 or so looking for design documents (having been asked to write many). Eventually I realized there are none. At least almost none, and very few that existed prior to the related software being written.

[jsty]

The AWS Lambda PR/FAQ was released late last year - worth a read

https://www.allthingsdistributed.com/2024/11/aws-lambda-turn...

[dboreham]

Also not a design document?

[anal_reactor]

The problem with design documents is that they require maintenance which takes more effort than it solves problems.

[teiferer]

What kind of maintenance do you mean?

A design can evolve over time, but a design document's objective is to document what was going to be built at that time. If something changes, make a new design document. (Similar to blog posts or news articles, they also don't evolve over the years. You write a new one.)

It sounds like what you mean is system documentation, a handbook of sorts, and that's what needs maintenance. But that's different from a design doc.

[anal_reactor]

> What kind of maintenance do you mean?

> If something changes, make a new design document.

This one.

[closewith]

Without fail, people who say this really mean "I am unable or unwilling to put in the hard work at the design stage to resolve uncertainty and will instead push these problems downstream to the development process where hopefully no-one will remember I'm responsible for the ensuing mess".

[anal_reactor]

Yes, that's correct. In other words, my cost-benefit analysis concluded that shipping fast and iterating later is a much better strategy than spending countless manhours on plans and meetings in order to provide a product that is perfect from technical perspective but misses both the timing and market needs. I don't understand this fetishation of "perfect code" when experience shows again and again that for most use cases, the correct approach is to ship fast and fix later. We're not sending a spaceship to Mars, we're making an AI-based social media app, either we ship this week or next week facebook will launch its own version which will make our product completely irrelevant and being first to release a feature is the only way to capture a statically significant part of the market. As long as the most common use case works we're grand, if 80% of the app doesn't work that's fine because 80% of the users only use the main 20% of the app, and the focus is on making sure that this works correctly.

[closewith]

> I don't understand this fetishation of "perfect code" when experience shows again and again that for most use cases, the correct approach is to ship fast and fix later.

You're conflating two separate issues, because design documents help you ship faster and fix later. They do this by making you think about what you're building, thereby allowing you and downstream consumers of the plan to focus on a smaller and more valuable set of goals.

Your approach is the opposite - building by gut feel and ignoring the available data. That's leads to wasted effort and elongated development cycles.

> my cost-benefit analysis

You don't plan, so you don't know your costs or benefits.