Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How to write an effective software design document

refactoringenglish.com

Post reply on HN
Print view View original

121–130 of 132 posts

Re: How to write an effective software design document

#121

Post by mtlynch »

Fripplebubby wrote: post #114
mtlynch wrote: post #102

Earlier quoted context omitted.

I find that LLMs are still worse than humans at limiting complexity, which is one of the most important outcomes of a design review. 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 des…

I do agree with you put I would push a little further - is it that complexity itself is the enemy? Or is it that the secondary outcomes of complexity (bugs, more effort to make changes, confusing code) are the enemy? If it is the secondary outcomes that are the enemy, and AI actually effectively allows you to mitigate those outcomes (debatable! I debate this with myself all the time!), then maybe we should embrace th…

> I do agree with you put I would push a little further - is it that complexity itself is the enemy? Or is it that the secondary outcomes of complexity (bugs, more effort to make changes, confusing code) are the enemy?

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.

Re: How to write an effective software design document

#122

Post by jmaw »

fg137 wrote: post #91

> A good design doc can save you years of development time. 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.

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.

Re: How to write an effective software design document

#123

Post by jmaw »

lefra wrote: post #99

Coming from an optics/electronics background, it's fascinating to see how much debate there is here around whether a design document is useful or not. I don't think any engineer outside software would start a project without writing at least a few paragraphs to make sure everyone agrees on what needs to be built, and that there's no major blocker. I blame the low cost of iteration in the software world (even lower no…

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.

Re: How to write an effective software design document

#124

Post by AnimalMuppet »

barrkel wrote: post #105
AnimalMuppet wrote: post #95

Earlier quoted context omitted.

If what you said doesn't make the AI think of changing that code, why is it going to make the AI auditor think of testing that code? That's what a gap looks like: Nobody changed it, nobody tested it, but some business constraint is now left in an inconsistent state because some piece got updated and another piece did not. Here's an example. You updated the code that interfaced with the database. But you forgot to upd…

When I've worked with systems that had these kinds of characteristics, we had checklists. A long list of "have you thought of X". You can't rely on someone writing a design to think of these things either! You need to have a process, and the process applies whether you dive into the code, dive into the spec, or have an AI dive into either. It's orthogonal. To be clear, I'm not suggesting blindly deploying an AI-writt…

Well, yes, I'd expect a checklist to be used as part of creating the design document. If there's a separate auditing tool that also knows about the checklist, yes, that's useful.

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!

Re: How to write an effective software design document

#125

Post by cryptonector »

bob1029 wrote: post #10

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 the expense of a much longer delivery timetable. Even high level software delivery contracts never seem to stay on rails for very long. It is often faster to just build the damn thing and see where it lands. Software is not like a nuclear power plant or offsh…

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.

Re: How to write an effective software design document

#126

Post by cryptonector »

RaftPeople wrote: post #107
bob1029 wrote: post #10

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 the expense of a much longer delivery timetable. Even high level software delivery contracts never seem to stay on rails for very long. It is often faster to just build the damn thing and see where it lands. Software is not like a nuclear power plant or offsh…

> 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?

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

Re: How to write an effective software design document

#127

Post by cryptonector »

Design docs are great for some things. In particular they are good places to document interfaces and contracts for those. However, for interfaces it would be better to have architecture documents instead of design docs, with design docs really being internal details.

Of course, few companies make this distinction between architecture and design, so in practice design docs are a mix of architecture and design.

Re: How to write an effective software design document

#129

Post by 0xbadcafebee »

murlax wrote: post #54
luc_ wrote: post #30

Earlier quoted context omitted.

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.

We have debated this a lot in our organization. We are tired of seeing low effort Tech docs that puts the onus on the reader than the writer. I think that the writer should spend at least an order of magnitude of time more than the reader. If not, then the design doc can just be the LLM prompt that generated the document. I have actually resorted back to hand crafting TDDs and focusing on 1-2 page docs. It is a great…

I agree that we should basically be requiring hand-written-only design docs, because it should force people to make sure they know what they're getting someone else to read. But there's two problems I run into:

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.

Re: How to write an effective software design document

#130

Post by hotelrwanda »

bob1029 wrote: post #10

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 the expense of a much longer delivery timetable. Even high level software delivery contracts never seem to stay on rails for very long. It is often faster to just build the damn thing and see where it lands. Software is not like a nuclear power plant or offsh…

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
Post reply on HN