5 ms·

I've never experienced a situation where a software design document meaningfully improved the overall process. At best, it helps to keep the business in sync at

• felixgallo 12d ago
  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.
  • fmbb 12d ago
    > you have not optimized for quality, extensibility, customer experience, or maintainability A ”software design” document does not optimize for either of those.
    • blanched 12d ago
      Why not? “Customer experience” is arguable, but most design documents I’ve seen involve the others.
    • AnimalMuppet 12d ago
      The absence of a software design document can definitely harm quality, extensibility, and maintainability.
  • phuff 12d ago
    Welcome both of you to the agile vs waterfall arguments of 25+ years ago. :) 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.
    • gfody 12d ago
      25 years ago the agile manifesto taught us to go extreme by taking our well written, sea-level consistent use case documents and shredding them into user stories, that can fit on stick-its. it's a pretty good idea assuming you actually had something to shred - but then we started writing user stories instead, sea-level depending on who wrote it, functional cats mixing with non-functional dogs, under water and then raining frogs.. soon said the devs: we don't need no stinkin' docs
• tobyjsullivan 12d ago
  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.
• 1over137 12d ago
  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.
  • bartread 12d ago
    Same goes for highly regulated financial environments. If you work in banking you generally can't just FTX-and-hope your prototype, which is very much what GP sounds like they're advocating. 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.
  • superxpro12 12d ago
    I reflected upon a consumer product I worked on the other day, in the power tools market, and the damn thing had 3 processors in it. 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.
  • trueno 12d ago
    at least where i work the onus of "who creates the design doc" ends up on the developer.. who also builds the thing.. and thats just like a 2.5x translation tax on the developer who's realistically putting it together to appease business heads who want to feel involved. 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.
• verdverm 12d ago
  > 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.
• pif 12d ago
  The software development realm is bigger than web programming.
• 0xbadcafebee 12d ago
  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.
• mtlynch 12d ago
  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.
  • luc_ 12d ago
    I think in the age of AI coding, these rationales are a bit outdated. And if you think they're not - I'm curious to know why you think so.
    • ambicapter 12d ago
      Can you explain in which way they are outdated?
    • mtlynch 12d ago
      > I think in the age of AI coding, these rationales are a bit outdated. And if you think they're not - I'm curious to know why you think so. Can you share more about how you think AI invalidates these rationales?
      • barrkel 12d ago
        The biggest thing AI enables is cheap code. 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.
• pydry 12d ago
  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.
  • pumphaus 12d ago
    > 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. 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.
    • pydry 12d ago
      yoloing your way to a first prototype and aggressively refactoring along the way does make a lot of people very uncomfortable but it still produces better architectures than BDUF or even a scaled down BDUF (LDUF?). 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.
  • 12d ago
• esafak 12d ago
  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.
• AnimalMuppet 12d ago
  > 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.
  • barrkel 12d ago
    Instead of thinking through all the places in the code the AI is going to have to touch, why not kick off three parallel agents implementing the thing and finding out what they did and the tradeoffs they found? 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.
• poincareball 12d ago
  [dead]
• rand_r 12d ago
  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.
• zer00eyz 12d ago
  > 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.
• sigbottle 12d ago
  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.
• RaftPeople 12d ago
  > 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?
  • cryptonector 12d ago
    At Sun we didn't use design docs for this. We used architecture docs instead. These were of the form of PSARC cases with materials such as: - 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 algorithms
    • RaftPeople 12d ago
      I was thinking in terms of a broad usage of "design" which tends to match what you wrote about architecture.
      • cryptonector 11d ago
        Often people mean "architecture" when they say "design", yeah.
• avgDev 12d ago
  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.
• suttontom 12d ago
  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.
• cryptonector 12d ago
  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.
• hotelrwanda 12d ago
  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
• trinsic2 11d ago
  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/ https://www.scottrlarson.com/blog/article-crm-obsidian/ I think this is a good idea. Thanks to the author.
• sigsergv 11d ago
  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.