[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.

[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".