How to write an effective software design document
refactoringenglish.com
refactoringenglish.com
It is often faster to just build the damn thing and see where it lands. Software is not like a nuclear power plant or offshore oil platform. You do not need to prove a whole lot of things in advance of construction. No one actually has to give you permission to do anything. You can email a link of a vertical slice prototype to the business whenever you feel like it. That can be the "design document".
A ”software design” document does not optimize for either of those.
The agilists I think ended up having pretty good answers for finding a sweet spot between small iterations that maintained quality while minimizing Big Design Upfront to prevent spending a lot of time preplanning the software, allowing a well functioning agile team to maintain reasonably high quality, extensibility, maintainability and satisfaction of actual customer needs while keeping velocity high and not getting bogged down in design heavy tar pits which were ended up not fully anticipating problems encountered during actual execution.
If that doesn't sound like a buzzword filled sentence I never expected to come out my mouth... But. The bottom line is: if you can keep your execution goals small and focused enough, you can iterate quickly towards a design with better information than you would have if you were to do a design study because you'll be better informed by the actual needs of the execution process than by what you _think_ the execution process will require at design time.
For starters you're going to have traceability requirements that can only be satisfied if you have a product requirements document and then often a software design document. Now you might well choose to manage all of that in JIRA and Confluence (or whatever) rather than sitting down and writing an actual document intended to be laid out and printed on paper but the fact remains the documentation exists and, indeed, is a must to satisfy compliance and regulatory frameworks.
As always, the domain you're working in and the organisation you're working for make a huge difference but, as much as there are plenty of places where none of this stuff matters at all, there are also plenty of places where it's incredibly important and that isn't going to change anytime soon.
I mean... when i was golfing, the cart had a gps enabled, cloud connected display that showed the golfers positions in front of us. I had a smart phone and a smartwatch with meter-accurate positioning to take a shot.
Software is beyond everywhere at this point.
i can think of... zero times where a business-coded person even a technical PM (which is a role i do appreciate btw) has ever come up with an official design doc or specification that didnt suck. creating a good design doc is either going to require an architect/staff or senior engineer to sit down and just do it. the overworked architect or staff engineer inevitably gets dragged in if the developers hands are full, or they just beat the shit out of the developer and fill their calendar up with meetings and make them do it... then they beat the shit out of them again and make them build it.. then they beat the shit out of them repeatedly doing fast follows for months and say "no not like that"
i think everyone wants to take some pride in the org they work at and maybe they feel like they've got the formula for sucess, but i personally haven't seen it. there's always going to be an additional translation tax required of the developer(s) who is/are also building the damn thing at the end of it. cover it in poorly run agile/jira shenanigans and this just slows down the possibility of getting to a super stable state back soooo far.
i actually agree with the guy a couple posts up: do some loose design work, friggen dropkick/prototype and see where it lands and go from there. i like facepalm when i hear that our project guys were planning a project for a year and when it was finally time to move on it every specification they planned out missed all the details. this is totally so much worse now with AI writing everything everyone is putting together.
Documentation is important for platform, and probably nothing else.
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.
> 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.
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.
Can you share more about how you think AI invalidates these rationales?
That means you could choose to try three (or more) genuine implementations and explore their tradeoffs, instead of making three proposals in a document with one recommended (and the other two usually only provided for contrast).
I do think the design is important to keep around - in particular, the constraints, the communication points, schema, tacit things that might not be clear in code. I am not certain that the design should precede the implementation for features below a certain size though.
Larger efforts need milestones and collaboration and will have multiple people doing implementation, so there's more need to agree schemas, APIs etc up front there.
Agree, but in my experience that doesn't change much about the design doc.
I think it's helpful to the author to be able to say to an AI agent, "Hey, put together this quick prototype," and that informs the design doc. But if the goal is to review the design decisions with the team, I don't see how you get around the design doc. I don't want a teammate to send me 10 KLOC of AI-generated code and ask me to review the design. Even if you told AI to try 10 different ideas and pick the best, I don't trust AI to make the same decisions as my human teammates.
I would try and get an understanding of design space by giving a good agent a high level goal and seeing what it does, then getting a summary of the approach.
When you do this several times, especially if you give it a steer on some non-functional requirement, you can compare and contrast different approaches.
The idea isn't to prototype so much as to gather information by doing. Prototype, to my mind, suggests other things; shortcuts, stubs, incompleteness. I would actually ask agents to do the whole thing, and find out the full scope. It can be particularly useful revealing side effects.
Pair it with code auditors wearing different hats, of course.
I get the impression that Fable, when well directed, is better than maybe 80% of SWEs. Maybe more.
[edit: Yes, I'm maybe baiting other users, but I want to know your honest opinions on this.]
If I tell a senior SWE that I'm creating a Discourse-like discussion forum, and I want users to have three options for selecting an avatar: (1) import from Gravatar, (2) upload a JPG or SVG or PNG or GIF, or (3) let the user draw their avatar on a canvas, the LLM will happily go and design that and write a 5 KLOC implementation, whereas a good SWE would push back and say, "That's like 10x the complexity of just allowing JPGs. How about we simplify it to say that in v1, the only option is to upload a JPG."
I've tried working with Fable/Sol and saying, "Look for features that we can simplify to reduce complexity," and they don't understand. They'll guess at features we can cut entirely, but they fail to see how to capture the essence of the feature without the complexity.
I've noticed this a lot with Fable recently. Like I'll say, "Show an error message in the web UI if X fails," and Fable comes back with this like 800 LOC error message generator that has switch-cases and combines inputs from three different sources when all I wanted was something like, "Update failed: database is locked."
I agree, but I think we're still a long way away from being able to trust AI to manage all software complexity for us. For one, LLMs frequently get tripped up by their own complexity. But even if the complexity didn't make LLMs more error prone or expensive to run, you still often need a human in the loop to understand what the system does.
I think of it kind of like compilers. Compilers do a good enough job that 99% of developers don't understand code at the bytecode or machine instruction level, but if we lost that last 1% of programmers who understand CPU instructions, we'd be in serious trouble.
For many systems, I'd argue technical documentation to understand how the internals are working can simply be handed off to the robots. Or generated on the fly. And if a requirement on the product level is not met, that can be changed under the hood.
As the other commenter said, "code is cheap" now.
In a way it's a return to waterfall, just with faster implementation phases.
Enter... documentation.
The most important thing that a good design doc does is specify what's in and out of scope. The second most important thing is to precisely define common vocabulary - what are the important concepts in the problem you're solving, and how should they relate to each other? All of that information serves to ground the day-to-day work in what's important. I find myself starting every Claude session with "read this doc and get familiar with the world, then we'll get to work on a part of it".
(The same is true when working with humans, especially but not limited to junior engineers who aren't used to managing a project longer than a week or two. AI coding agents just never grow out of that phase.)
I guess my question stems from being rigid how a design doc should be defined, argued over, and then executed by humans. I think some of the details simply don't matter, and if they do, they often can be changed relatively quickly in order to adhere to the new requirement.
Try the claude-mem plugin.
I have actually resorted back to hand crafting TDDs and focusing on 1-2 page docs. It is a great way to organize my thoughts and create a shared mind space among other engineers. My 2 cents.
1) A lot of people who write design docs, RFCs, etc, don't write them well. I end up needing to get them on a call and explain their entire idea to me because it's the only way to pull the details out of them.
2) Regardless of how much I write by hand, I still have engineers who are so incredibly lazy that they just don't read the docs at all. They can't be arsed. So I have to get on a call and basically explain the whole doc to them.
This is starting to lead me back to what other people hate: meat puppeting. Telling Claude my idea, Claude writes it up, and I ask that engineer to ask their Claude to read my Claude output and summarize it for them. I really want a better solution, but our engineering management is almost nonexistent, so nobody does anything they don't feel like doing.
Designing in a group can be very difficult, and doing it well is a skill set that most people don't naturally have.
I think this explains your point 1. Why do people view designed docs as pointless? Because they really don't have a vision or model for what and effective and healthy collaborative design process would look like.
Not only is it a skill every participant needs to have, they also all need to have a similar amount of competence and knowledge about the domain as well as the current implementation, otherwise it's mostly pointless ime.
But if all ven diagram circles overlap ... It is nice. I can count the times this materialized (in my professional life) on one hand. So I'm generally more towards the "make a prototype, then explain it to the others. Either it's the baseline for the discussion or the illuminating event that clears up wherever this approach works with that team.
Often, the group members presented to, do not have the required knowledge to critique the design document.
I have seen people proposing (demanding even) changes based on vague feelings and their need to be seen as contributing.
Once they say something, it is out there, now it is the poor presenter who has to refute it or accept modifications to the design.
I can think of situations where design document(s) would be a clear use, and I think that would be a better way to respond.
3. The developer is not able to imagine how the design works because s/he has no capability for abstraction. Needs to go hands-on.
I might add that writing the doc is not the purpose, the purpose is to think it, challenge it and share it.
3. The business cannot figure out a direction so the developer can either churn on design docs fruitlessly or make prototypes that visually show the business people what our options are in order for them to make up their minds
so you're best off writing a small one that you do your best to hide, and make a few fancy ones per season with graphs and absurd will-never-be-implemented details for the higher-ups to be distracted by.
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.
Only if people actually do that.
I've joined a project where a design doc should've been written before the first line of code (as per the agreed upon dev process). Developers disregarded that and yolo'd their way to a first prototype. No documentation whatsoever. Then someone else was tasked with writing a design doc for that big ball of mud. You can imagine how that went.
I've joined the project only much later. At every corner I'm dumbfounded by the "design decisions". Refactoring now is a herculean task and kept to the minimum required.
I'm certainly not advocating for waterfall-like "make a plan and stick to it no matter the cost". But looking at the requirements and drafting a coarse design from those goes a long way. At least you can get idea if whatever you have though up is in agreement with the requirements.
Treat the design document as a living document. Do a coarse draft first. Implement. Refine the doc with stuff you've found out, ditch the stuff that didn't work. As a bonus you get a relatively neat on-boarding doc for people joining later.
it's really not generally appreciated just how much better architectural decisions made in the context of refactoring are. if you have a time budget for architecture it will always be better spent on refactoring than writing documents in advance, no matter how minimal they are.
Throw the document away, it doesn't have any value.
But thinking through what you are going to do, in some detail, is valuable.
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.
Planning is essential but it doesn't survive contact with reality. However, AI makes contact with reality cheap! Why not use it to improve designs, by writing the design after a few implementations have already been made?
Only slightly tongue in cheek.
Here's an example. You updated the code that interfaced with the database. But you forgot to update the stored procedures within the database. As a result, the database is now being put in an inconsistent state with every transaction that uses your new code. That is the kind of thing that a software design doc can help you remember, because it is supposed to make you think through all the stuff.
And if you're going to say "Your business stuff shouldn't be able to get into an inconsistent state", well, there's a lot of businesses that have potential landmines laying around. You can say they shouldn't. You're right, in an ideal world. But in this world, they do, and you have to live and work in the world that we have.
Now, in fairness, a good AI check might turn up that the database was left in an inconsistent state... if it understood the constraints well enough. If. I wouldn't want to gamble my production database on the AI's understanding and testing of all the constraints, though.
It's orthogonal.
To be clear, I'm not suggesting blindly deploying an AI-written spike implementation to production, but rather using it to elicit information for better designs.
The fact that a probe that goes off and modifies tables X, Y and Z to achieve the feature gives information for an AI auditor to look for other uses of X, Y and Z, and discover things humans may miss, because with good guidance and a proper harness, AI is usually more persistent and thorough than people. It can turn search results into a checklist and the harness can track completion, and so on. I am far from convinced that your example would not be found via this route.
But if you're doing a spike, no, don't do a design document for it. How can you? You don't know what the design needs to be yet!
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.
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.
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?
- interfaces lists, with attached commitment levels
- interface contracts where interface commitment levels do not otherwise allow teams A, B, and C to use each other's interfaces.
That's much better than design docs.
The difference between architecture and design -at Sun anyway- was this:
- architecture is only about interfaces
- design is about details like algorithmsGood 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.
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.
[0]: https://www.scottrlarson.com/blog/article-crm-obsidian/
I think this is a good idea. Thanks to the author.
I learned to write design docs at Microsoft and Google, and I thought they both had good culture around docs that hasn't percolated out as well as other engineering practices at those orgs. I haven't seen a thorough explanation of how to write design docs, so this is my attempt to externalize what I've learned about writing them.
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.
This is a good question, and I have a super long answer that's been in my head for like 8 years about how to influence your teammates to adopt good engineering practices.
The short answer is that most useful software engineering practices are a risk to the first person on the team to adopt them. For example, if everyone on your team thinks automated testing is stupid and you adopt automated testing, it will look like your work is worse because you're slower in the short-term, and maybe you have to do even more work when teammates break your tests.
It comes down to accruing social currency with your team. Your teammates don't want to take a risk for you if you have a history of bad ideas that wasted everyone's time. But if, for example, you implemented automated deploys to replace a tedious workflow developers had to do manually, people would see how your ideas have payoff, and they're more willing to invest a little bit if they expect ROI long-term.
When I've convinced my teammates to invest in design docs, I made sure I had some wins under my belt before I started pushing for everyone to write design docs. I invested a lot in docs myself so my teammates could see the value before I asked them to start writing.
This is also a place where you have to think about politics a bit. Documentation has a much better shot if it has support from the top, so think about the pitch to your manager or dev lead about how design docs make their jobs easier.
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?
What you're describing sounds like toxic team dynamics rather than something specific to design docs. Do you work effectively with your teammates outside of design docs, or is there similar tension/hostility everywhere?
What you're describing sounds like the design process working as intended (modulo the finger-pointing). The design doc should be unambiguous, and the implementation should match it.
Assuming this isn't just symptoms of a sick team, my other explanation is that your teammates find your deviations from the design doc unexpected. It sounds like you're running into situations where you can't implement the design doc as written, so you're proactively making your own design choices and showing your teammates the implementation. Could you loop your teammates in earlier on before you've implemented the code? Like, "The design docs says we're supposed to use SQLite, but I realized that SQLite doesn't support types the way we expected, so I think we should switch to Postgres for X, Y, and Z reasons."
So, I think I didn't elaborate on the process enough to get the answers I was looking for. Here's what happened.
1. I would uncover a requirement from the business 2. The conceptual design would be written, high level understanding of the feature etc that was trying to be written 3. Conceptual design would be signed off 4. Logical design would take place ( I think this is basically everything from the Constraints section down in your model ) 5. Logical design would get reviewed and signed off.
Now technically everyone could and was encouraged to sign off the logical design, but in reality maybe one other person in the team would, I don't really know the reasons why.
Then implementation start, this was usually NOT me but another team member tasked with the design, and this is where the process really started to fall down with the onus being put squarely back on me as to why the design didn't work :)
I also actually tried the other approach, implement as much as possible ( because AI fast ) and then reverse engineer the design, but then that very much felt like, what the hell is the point now? I might as well just use the standard code review process.
Does that make sense? Sound familiar?
Most significantly, it's strange for the person writing the design doc not to be the person implementing the code. This is asking for trouble because there's a principal-agent problem[0], and also there's bound to be signal lost in the handoff between designer and implementer. It's not so unusual for the design doc author to work with a team on implementation, but they'd still be actively involved in implementation, which sounds different from what you're describing.
I've also never heard of this separation between a conceptual design doc and a logical design doc. I've been on teams where the product manager writes a UX-focused spec, and then the dev writes a technical-focused spec, but I've never heard of a conceptual vs. logical spec.
Does the org have a strong engineering culture in other ways? Like automated tests, automated deploys, automated monitoring/alerting, useful code reviews? Because the easiest answer is that you're in an org with poor software engineering practices, or at least weak documentation culture, and the design review process you're experiencing is there for historical or political reasons rather than engineering reasons.
[0] https://en.wikipedia.org/wiki/Principal%E2%80%93agent_proble...
For instance the enterprise architect/solutions architect ( or whatever job title is fashionable at the time ) would write the document and then send it over to the development team and obviously that wouldn't work.
I actually adopted the conceptual/logical design from two ex Hewlett Packard engineers/architects who introduced the idea to me, probably some twenty years ago now!
Yep we're strong in many other ways, but finding the transition to AI challenging :)
Reviews have somewhat turned into, I send you the output from my AI agent of choice, and you tell your AI agent of choice to fix it :)
Thanks again for the time taken to reply :) It is appreciated.
- 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.
I think they're valuable, both because they get you to think through the actual functionality (and underlying implementation) of the software, and the make sure that you and the [person you're developing for] are roughly on the same page. Plus, every edge case or design issue you catch while writing the spec saves you a ton of time.
That said, I think a big weakness of specs is that it's just not possible to write a perfect spec that doesn't have any blind spots and covers all the edge cases and issues you'll run into when actually developing. This makes it more difficult to hold the customer accountable to the spec, since you (the designer and devs) can't really be accountable to the spec unless you want to deliver some overly literal, not-actually-helpful product.
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...
Unrelated - I really dig your "my [x]th year as a bootstraped founder" series.
1) Add a section called "Potential Changes". This is broader than "missing features", and can include other items too, such as new hardware that might become avaliable, customer requirement changes you might anticipate, possible new technology (e.g. a new database or cloud service that might be useful), multilingual support, etc. Listing some of these often causes reviewers to think of others as well.
Ensuring the design is modular around such changes means implementing any of them will be far easier than if assumptions are hard-coded throughout the codebase.
2) Security and privacy are two aspects of a more general category of "compliance assurance". Those two are worthy of their own categories, but you should have a section covering any other legal, regulatory, or corporate requirements. The plan for auditing these compliances should be listed too.
Often, of course, there are none beyond security and privacy.
OP's design document is comprehensive enough to cover much of ground of the full documentation package for regulated software submissions. Basically all that's left is tracing requirements to design to verification method to verification result.
- One of the things about design you notice as you get older, is the bigger a software application is, the worse your options are later on. The design doc can be considered a proxy for the application: the bigger your design doc, the bigger the application will be. You should still try to think about as much of the app as you can in your design doc (don't intentionally try to make it small and miss things). But if you start to notice this doc is getting pretty heavy, that may be a hint that the application is trying to do too much.
- Next suggestion: make C4 diagrams and split up your design doc by each level. You don't need to make perfect C4s, or even have a good handle on how to define them. You just need four levels of abstraction by which you'll give the reader a picture of how your application works and fits into larger concepts. This will help you and the reviewers understand it better, and will likely also elicit more questions, which helps you better define the design.
Example C4 layout:
SLAs & SLOs
- Interfaces & Logging
- Monitoring, Alerting
- Dependencies
- Security / Privacy / Legal
- Infrastructure
It reads more like a CONOPS or a software architecture document, but its not detailed enough from a high level perspective, and too detailed at a low level perspective (ie. it has implementation details in a few places you wouldnt expect in a higher level design doc).
In that light, I'm not sure who the audience would be in a corporate environment. Is it for architects, other developers, or yourself?
I've started to build docs structured as a skill. Since every model/harness is trained to handle skills well today. The entire docs of a project or modeled as a skill.
I also have additional frontmatter on the md files. Specifically 2 keys -> when should you read, when you should not read this doc. This with a simple cli to help parse this has made the docs experience much quicker and nicer.
You can also generate svgs, mermaids etc on the fly now when you are really stuck on something.
A good implementation of something like this is https://deepwiki.com/ for OSS projects.
Documentation of the project are the projections of coded intent at a higher zoom level. C4model is an amazing concept and applies well to the context management and docs
Software is still the best specification for existing behavior..
Is there a rule of thumb for when it’s enough to update the existing document, and when the design has changed enough to justify a new design doc and another review?
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.
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.
So far my best experience has been to feed the whole thing into AI and get an overview of the project. That together with a few quick bullet points about the overall purpose of the system is pretty workable.
* 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 only have a few years of experience in this business, but I have seen numerous cases where none of this matters. Your perfectly drafted plan could easily be derailed by technical limitations, customer request or company reorg. You are better off use that planning time for something else.
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.
These are not guaranteed to happen. But if you don't have a plan, you will be derailed very soon and practically inevitably.
I used to like reading (or skimming) Lynch's articles, but seeing how he's profiting from gaming the system tarnishes it for me.
- threads being left open and ambiguous - lack of proper context in the beginning
I actually found the linked article even more helpful, which is how you should have design docs reviewed.
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.
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...
> 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.
What worked for me was to ask Astra/Fable to include pseudo code in the design doc. which comes to 1-2 pages. Easy for me to skim and change the direction/approach. Rest all of the flowery language is for LLM giving context.
Of course, few companies make this distinction between architecture and design, so in practice design docs are a mix of architecture and design.
I blame the low cost of iteration in the software world (even lower now with LLMs).
> Interfaces section
Only real criticism I have here, is I would not include any code in a design doc, unless it is really really vitally important. I've seen a lot of design docs (especially in the LLM age, written by more junior staff) which are effectively just an English summary of code. The point of a design doc is (generally) not to explain that you're going to have a WidgetManager and WidgetFactory class and what specific properties and methods they have, it's to explain how the widget creation workflow works and maybe you have the WidgetManager/WidgetFactory in an architecture diagram. As a general rule, if you're starting to include actual code, you've gone too low-level, IMO.
> Not all design decisions are equally important. Some choices are more permanent than others.
At AWS one of the corporate culture memes was calling a decision either a "one-way door" or "two-way door". Just asking yourself the question, if we had to walk this back, is it truly irreversible or just an inconvenience? Turns out most day-to-day decisions are two-way doors, particularly engineering ones. Even if the choice made is wrong and a bunch of work needs to be done to switch back, it's still preferable to what a lot of companies end up in, which is decision paralysis where every change needs approval from multiple committees, resulting in months or years before work can start. Note that this doesn't meaningfully increase the odds the decisions made are the right ones; it just delays the implementation and diffuses responsibility if the wrong decision was made.
> A from-scratch rewrite would never work, and even if you manage to write new code in Rails, you’re still maintaining code in two wildly different languages.
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. Not to say that it's the best use of your time, or that you shouldn't do your due diligence and pick the right language up front, or even that the original 2000 article was about a language-to-language rewrite (the Netscape rewrite was an architectural redesign).
[0] https://www.joelonsoftware.com/2000/04/06/things-you-should-...
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.
Brainstorm with your agent in a new session, ask a thousand questions, at the end ask for a detailed prompt.md to develop an app then tell it to comply
There, saved years of development time in AI era
In all seriousness a big chunk of my work is reviewing docs and 100% of the design docs I read these days are generated and there is a lot of slop. I have to parse them with AI to make sense of them, contributing to the problem. I wish people would follow a sensible set of rules like this one.
Did anyone have any solution to this dread? Or cracked the code on how to write docs that have other agents as their primary audience?
Yes. Don’t “write” your design docs with AI. If you can’t personally enforce that, get your manager to.
If you can back them into a corner and force them to admit they don’t even understand something they supposedly wrote, use that as an opportunity to remind people it’s not acceptable to generate design documents that you don’t understand and then push them off onto other people.