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

101–110 of 132 posts

Re: How to write an effective software design document

#101

Post by CurleighBraces »

mtlynch wrote: post #84
CurleighBraces wrote: post #74

Earlier quoted context omitted.

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 bu…

Thanks for reading! 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…

Thanks for taking the time to reply, please take my response as earnest attempts to better myself :)

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?

Re: How to write an effective software design document

#102

Post by mtlynch »

luc_ wrote: post #96
mtlynch wrote: post #71

Earlier quoted context omitted.

> The biggest thing AI enables is cheap code. 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…

Why do you need to review design decisions with a team anymore? 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.]

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

Re: How to write an effective software design document

#103

Post by lirolero »

luc_ wrote: post #96
mtlynch wrote: post #71

Earlier quoted context omitted.

> The biggest thing AI enables is cheap code. 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…

Why do you need to review design decisions with a team anymore? 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.]

[dead]

Re: How to write an effective software design document

#104

Post by dontsubmit »

Lovely writing and highly inspiring. I face many issues like this at my company including but not limited to

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

Re: How to write an effective software design document

#105

Post by barrkel »

AnimalMuppet wrote: post #95
barrkel wrote: post #81

Earlier quoted context omitted.

If the feature works, and passes AI auditor agents with various hats (thinking of auth and security in particular), did that code you're not thinking of need to be touched? What effect did it have that cannot be captured in side effects, tests or audits?

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

Re: How to write an effective software design document

#106

Post by pydry »

pumphaus wrote: post #93
pydry wrote: post #29

Earlier quoted context omitted.

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 contro…

> 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 pro…

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.

Re: How to write an effective software design document

#107

Post by RaftPeople »

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?

Re: How to write an effective software design document

#108

Post by SoftTalker »

barrkel wrote: post #63
mtlynch wrote: post #34

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. Can you share more about how you think AI invalidates these rationales?

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 b…

Even if it's cheap, 3 implementations are more expensive than one and then you add the additional task(s) of evaluting them and selecting one to move forward with.

Re: How to write an effective software design document

#109

Post by avgDev »

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

Re: How to write an effective software design document

#110

Post by lekhoa88 »

mtlynch wrote: post #3

Author here. Happy to take any feedback about this post. 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.

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.

Post reply on HN