OP here!

I'll admit a lot of bias because I think design docs are extremely useful, but I find that when people hate design docs, it's almost always for one of two reasons:

1. The developer has worked on teams where design docs are viewed as a pointless ritual, so authors treat them as a pointless requirement and write bad docs and their teammates view them as pointless so they don't bother giving useful feedback, reinforcing everyone's belief that they're a pointless ritual.

2. The developer does not like other people questioning their engineering choices, and they know that it's harder for their teammates to push back on finished code than a design doc. Investing in the implementation before design changes the calculus to bias in favor of whatever's already implemented rather than what would have been the ideal implementation. Plus, it's harder for the team to review design decisions of 10k LOC than a 5-page design doc.

Software is in nuclear plants, cars, oil platforms, pacemakers, everywhere. If one is writing more ‘disposable’ stuff like flashlight apps for smartphones, then sure, as you say. Others are writing serious stuff, and design docs are invaluable.

It sounds like you’re defining design as UI/UX design. I think most people include (prioritize, even) things like system architecture, performance bounds, etc.

It's been quite helpful when your project needs expertise from other people, and you want them to vet your approach and find gaps. Doing the up-front work of explaining the context and structuring the project in an easy to understand way makes it more likely for busy people to engage with it and help you out. Of course, it's helpful as a rubber-duck exercise on its own, so I would err on creating one, even if just for myself, for anything high-risk or hard to change later.

The software development realm is bigger than web programming.

You have successfully optimized for fast, but you have not optimized for quality, extensibility, customer experience, or maintainability. Fast can be a great thing to optimize for, but there are many other situations where other optimizations are preferable.

> At best, it helps to keep the business in sync at the expense of a much longer delivery timetable.

If you're writing a software design document that slows down your delivery timetable, you're doing it wrong. (Or, more charitably, your business is doing it wrong.) If your design document is to keep the business in sync, you're doing it wrong. That's not what a design document is for. It's for keeping you in sync.

> It is often faster to just build the damn thing and see where it lands.

What are you building? If you don't know, then sure, it's really hard to write a design document. At that point, you're doing exploration, research, not development.

But even when it's an exploration project... once you've found something worth doing, take a day or two and document what you're doing and how you're doing it. Think through all the places in the code you're going to have to touch, all the other things it has to interface with. Make sure you're not going to leave a gaping hole in functionality or, worse, in security.

> Software is not like a nuclear power plant or offshore oil platform.

As others have said, sometimes software is a nuclear power plant or offshore oil platform or airplane or medical device, or even just medical informatics. If you mess up people can die. Sometimes it trades financial instruments, and if you mess up it can destroy the company.

> No one actually has to give you permission to do anything.

On your own time, sure. If you own the company, sure. Otherwise, you need their permission to spend their time on things that they're willing to pay for.

Now, look, it's true that many places go too far overboard on "process". But YOLOing and cowboying isn't the answer either. They aren't even the answer if your single goal is to go as fast as possible. You go faster by spending the appropriate amount of time thinking through what you're building, how you're building it, and making sure you're not missing any of the big things that often trip projects up.

It's mixed for me because there are certain things that I clearly think are needed. For example I'm building a custom network architecture and it's to the point where I'm using frontier models to reverse engineer game clients (while battling against the cyber safety system) for the sole purpose of validating that the network architecture I'm making is, if not "useful" (cause there's the game itself), at least different and superior. And to me the designs out there clearly are evidence of things not designed well and thought through ahead of time and instead a patchwork of hacks.

But then there are aspects I'm missing because while I've thought about the network protocol deeply, I'm not, say, a game developer who's ever gone through the whole game dev lifecycle. There's common patterns with software dev but it ain't it. There are probably so many things I have not thought about w.r.t. the whole deployment process that I'm not sure if letting AI vibe design+code it out is good or if I need to sit down and deeply work out the things I don't even know I don't know.

It's always a set of tradeoffs between things.

> I've never experienced a situation where a software design document meaningfully improved the overall process.

If you don't have a document, then how do you make sure that internal team A and internal team B and internal team C and external vendor D and external vendor E all create the correct things so the entire system actually works?

I disagree. Having a design doc would have saved me some time having to rewrite certain parts of a CRM system I am working on in Obsidian[0]. Not having a plan on handling certain aspects up from can make more work.

[0]: https://www.scottrlarson.com/blog/article-crm-obsidian/

I think this is a good idea. Thanks to the author.

Design document provides another person's view to the system. It's like coding but without the actual coding. Reviewing design/arch docs is much easier than reviewing code because all important logic presented as-is, without needing to decode back from code.

100%. I find it's generally used as a waterfall practice - i.e. BDUF first with a design document, then implement instead of "implement following conservative assumptions, revisit and refactor aggressively".

The latter being vastly more effective at honing good design because more decisions are made in retrospect.

I find that a spike or a spike PR to demonstrate a new approach (if a software design decision is controversial) is 10x as valuable.

> No one actually has to give you permission to do anything.

For now, in the current context (with ai), it seems like a non-ignorable portion of society now wants to limit what kind of code people can write, Ai is apparently sufficiently like nuclear science that regulation may come to the act of producing code.

I mostly work on solo projects and the reason I create design docs is so that I can sit and think through cases quietly, although AI does most of the coding, writing the doc in as detail as possible is what makes me feel I am still in control

I cowboyed a lot of projects, then 2 years later a feature is not working as expected. It is.

Good docs, signed off by stake holders is essential. It basically covers you the dev, and confirms everyone involved agrees on what the software will do in certain situations.

When you need buy-in from others outside your team, you probably need a design doc. Even when you don't, if the design is not trivial then a design doc will help your successors understand what you were up to.

Your second paragraph is the impetus behind Agile Software, and we've all seen how fantastically that failed. Lots of code pushed out quickly, but also a lot of really shitty products, uncertainty, never-complete projects, dysfunction between teams, etc.

> Software is not like a nuclear power plant or offshore oil platform

No, but it does impact people's lives significantly. How many times has your personal information been leaked by a company making products by people who didn't care? Who would have predicted that a security company's terrible QA would lead to 8.5 million crashed systems, 42,000 delayed flights, 10,000 cancelled flights, and over $10B in economic losses? I'm sure the developers just said "not our problem". But their lack of concern, and "just throw shit at production" mentality, had real world consequences.

> It is often faster to just build the damn thing and see where it lands.

Part of documentation is figuring out if you're building the RIGHT thing. It give the opportunity to get feedback from more than one party.

The usability of most modern (complex) application is deplorable. I see things that a paper prototype with 5 people on the street should have stop dead in its tracks being rolled out with banners and trumpets.

And then no one ever wants to remove an unused or unprofitable feature. There is no bonus for it, no one puts that on their resume. But the feature you launched that really did enshitify the product gets put on there with 3 gold stars.

Have you never built a large piece of software that had tradeoffs? What if your teammate just goes immediately into implementation with an AI and the AI decides to use library Foo which is disallowed for certain customers and API Bar which uses a legacy IAM platform that your company is in the process of moving away from? What if there are privacy, security, or legal requirements? It's more important than ever to discuss these things with humans who know the system because an agent will blindly go off and find something that someone once made work and will use it as evidence for why that's the way things should be done.

I've written bad/poorly designed code and made decisions I regret and have had coworkers use that bad code to defend their design choices because the agent said it was the best available option.

Design documents also let the engineering team who will be reviewing your code get a high level understanding of all the pieces you're sending them. If you've ever worked at a large company or codebase it's insane to say these docs aren't helpful.

Have you never encountered code that you thought was designed fundamentally incorrectly, but was too entrenched to change? That's what design review is for.

[dead]

So I tried this and it failed miserably.

The documentation became the bible, and although I tried to keep the design goals at the conceptual/logical level the following would happen the moment the implementation started:

1. This is ambigous the docs need updating, please refactor your design 2. This doesn't work as the doc stated why did you get this wrong 3. The requirements have changed you need to update it

The burden to get "everything right" was absolutely lumbered of me, and the document became an easy finger pointing exercise, even if blame wasn't intended by those launching the critique the burden of "owning" the doc and the consequences of the doc was real.

Now there's a good chance that I am just a shit documentation writer, I can accept that, but honestly I feel like for the vast majority of organisations this just falls into another step of the waterfall pattern, which just doesn't work.

How do you handle this? What did I miss?

This is good guidance, but what do you have to say about convincing your team of developers to live it out?

I've found that developers usually like writing code and avoid contributing to documentation. For some, it's actually scary because (edit: for them,) high quality writing is harder than high quality coding, and it can be avoided quite a bit.

On the project side, it's rare for the implementation and verification stages to not consume all the budget and more, and delivery creeping past the original optimistic date. So there's no time or money to spend on documentation.

The combination is that even with your great advice in hand, it's hard to navigate to really solid and comprehensive design documentation underpinning the products.

Good read, although the document would be very lengthy if I am to write all the sections in the articles. I sometimes break down the design doc into multiple design docs.

- Manager doc : Summary(Background + Objective), User Story (Scenarios), High level architecture, open questions, task break down + timeline including other teams' tasks

- Engineering Architecture doc: Summary, Glossary, Goal (Functional + Non-functional + Non-goals), More detailed architecture & components between, open questions, tasks break down + timeline

- Engineering API / Database design doc: Similar summary + link to architecture doc. More detail information on API (eg: input params, output params, example client code) + database design (eg: database type + fields), open questions

Each doc is to be read within a single meeting. The shorter doc helps narrowing down the discussion scope.

Disclosure: I worked at Amazon where there is a typically 1 hour meeting session with the first 15-30 minutes dedicated to reading. It's probably why I multiple short docs over a single design doc. Telling people "Today, we'll read section 1,2,3,5,8 of the doc" didn't really work.

How are design docs changing in the agentic age?

Fun piece of trivia, Joel published one of his functional specs.[0]

As a huge fan of Joel's writing and engineering ideas, I was actually underwhelmed by his spec. It wasn't bad but it also felt like he missed a lot of opportunities to articulate design decisions to the reader more quickly or clearly.

One obvious mistake is that there's over a page (in a 20-page spec) just dedicated to coding conventions and what prefixes variable names will have. I think Joel later conceded that it was a mistake to cover naming conventions in a spec, though I can't find a link now.

[0] https://web.archive.org/web/20051028171624/https://www.joelo...

Referencing Joel Spolsky's article about how you should never do a rewrite is starting to feel outdated as well.

Why is diataxis outdated; don't your engineers ever read the code? Don't you think it helps the agents too?

Why do you think diataxis and the google guidance is outdated now?

Yeah, this is difficult.

My rule of thumb is to ask myself, "Is there a chance my reviewers would not have signed off had this been in the design doc they reviewed?" If the answer is yes, I send it out for a follow-up and explain why I had to change the design.

In my experience, the response from my reviewers is generally, "Yeah, that's fine." It's a combination of (1) the practical limitations that it's hard for them to get the whole design back into mental context to argue about it and (2) they trust that I'm taking the design seriously and have thought this through. I think occasionally, I've sent a post-approval change out and someone points out something

It's common to encounter a curveball nobody anticipated at design time, but if you just go rogue and unilaterally make design decisions, it degrades trust and undermines the review process, so I want my reviewers to know that I'm taking their feedback seriously.

This is not levels of abstraction, it's a dependency graph.

I think the design doc still has some value after it has been created. For me it almost acts like a checklist of things to be completed, and it's nice to have it in one place in bite-sized bits. My design docs will also have links to external resources and it's nice to have them in one place so I don't have to track them down later.

But I 100% agree that the majority of the value is gained in the writing of the design doc, and the decisions/tradeoffs that have to be thought through during that process. Which is why I strongly push back against suggestions of using AI to write design docs. Since delegating the writing to AI causes over half the value of the design doc to be lost.

I answered this in another comment,[0] and I don't think there's widespread agreement on this, but I think design docs should be a short-term doc that lives until the design implementation is complete. I don't think design docs are the right format for a document that has to evolve alongside the code forever.

[0] https://news.ycombinator.com/item?id=49698580

Don't know about efficient, but there is at least two ways which seem to work OK-ish (although not all that efficient, I gahter):

* Do regular certifications. Before certification, check if the document is up to date. If not, update it.

* Share the documents to answer teammates' questions. Like with a WIKI it may turn out that the important stuff is actually missing/undocumented/outdated. This is then a good opportunity to fix the document.

I would argue that the technical limitations should be considered during the creation of the design doc. In my experience, writing design docs can help me simplify the implementation because I've through through a lot of the headaches ahead of time.

But I will say I've seen many projects get ended by customer request or reorg. I think it's a cost-benefit analysis where you should consider the size of the project (and how long it will take to implement) vs. how long it will take to write the design doc. If it's a 2 day task, that is easy to change after the fact, then no need to write a design doc. But if it's a 2 month project that will have public endpoints that other teams or products will use, it likely is worth a 2-3 day design doc.

> Your perfectly drafted plan could easily be derailed by technical limitations, customer request or company reorg.

These are not guaranteed to happen. But if you don't have a plan, you will be derailed very soon and practically inevitably.

I found this article posted here a while back insightful: https://refactoringenglish.com/blog/useful-feedback-on-desig...

Start with a single reviewer who is invested in the topic has been helpful for me. Occasionally it is hard to even find one person with how scatter brained everyone seems to have become lately, but depends on who you work with I guess...

I think getting people to read design documentation was always the challenge; this is not a new thing.

I've both produced documentation and consumed it. When I consume documentation, I don't expect much. And to be honest, I don't like the low signal to noise ratio in typical design documentation. That was always a problem. Any sufficiently complex thing is just hard into a power point friendly diagram. And anything involving boxes and arrows where the number of boxes is 5 at best, is probably not that interesting to think about.

It certainly feels like this is an intrinsic friction point in a world where more and more of the actual code is written by AI. I know in my workflows, reading a design doc of any length is a big tradeoff of time that could be spent building. Which isn't a new problem to have, of course, but as the time from plan->code->review->deploy keeps racing downward, "reading design docs" feels like it's ripe for disruption as far as how much time and attention it takes.

Thanks for reading!

> Isn't much of this made redundant by being part of an existing system?

I haven't found that to be true in my work. If you're only making a minor change to an existing system, then you may not need a design doc, but a significant change to an existing system has as much, if not more, complexity and ambiguity than greenfield development.

> Also, this level of detail is a recipe for being outdated once the issues, compromises and compromises starts coming in

I think this is what people typically get wrong about design docs.

I don't think design docs are a good medium for being the perpetual, living description of the system. I think design docs should capture the design at the time of implementation. You should modify the design docs while you implement the work called for in the design document, but once you're done with that work, you freeze the document and preserve it for posterity only.

The design doc is about a specific change to the system. If you need a doc to describe the high-level architecture of the system as it evolves, that should be a different doc.

I think you're probably right. However I attribute the lack of upfront design in software is due to the relative ease of changing it after the fact.

If they constrain design they're relevant. Doesn't mean every legal detail should be in the doc.

Not what he meant, but for an outsider it could be hilarious to watch the company tumble because of that rule.

OP here.

Thanks for reading and for the thoughtful feedback!

> Only real criticism I have here, is I would not include any code in a design doc, unless it is really really vitally important.;

Yeah, that's fair. If I were setting guidelines for a large org, I'd maybe discourage code snippets in design docs, as it's hard to know when is too much. At my last company, the dev team was just 3-4 people, and I found it helpful to have little snippets in design docs especially when we're talking about semantics of a new library or how to migrate existing code to a new system.

> Orthogonal to the article, but this line of thinking (including the link to the classic 2000 "Things You Should Never Do, Part I" article[0]) may be worth reviewing in the post-LLM world; for all their flaws, LLMs are spectacular at language-to-language translation, and we already have one major project released[1] that shows porting a relatively large and mature project from one language to another is possible.

Yeah, I agree this could change with LLMs, but I think Joel is still correct up to today. Bun is an interesting case because it's friendliest possible conditions for an LLM rewrite (self-contained inputs and outputs, easy to test old implementation and new implementation side by side, huge test corpus w/ third-party tests). I haven't followed it closely, but it seems like the jury's still kind of out as to whether the rewrite was a good idea.

>Did anyone have any solution to this

Yes. Don’t “write” your design docs with AI. If you can’t personally enforce that, get your manager to.