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

71–80 of 132 posts

Re: How to write an effective software design document

#71

Post by mtlynch »

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…

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

Re: How to write an effective software design document

#72

Post by AnimalMuppet »

1over137 wrote: post #25
gbrindisi wrote: post #8

Claude, write a skill to create design docs as per this blog post /s 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 t…

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

Yeah, this. If it's slop, reject it, and tell them why.

Re: How to write an effective software design document

#73

Post by esafak »

Tsarp wrote: post #60
esafak wrote: post #46

Earlier quoted context omitted.

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

Its just far easier to ask an agent to do the first past ( with references to actual code ) and then start to dig in. A good implementation of something like this is https://deepwiki.com/ for OSS projects.

The code doesn't usually capture the whys; that is what documentation is good for.

Re: How to write an effective software design document

#74

Post by CurleighBraces »

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.

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?

Re: How to write an effective software design document

#75

Post by AnimalMuppet »

barrkel wrote: post #67
AnimalMuppet wrote: post #51

Earlier quoted context omitted.

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

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

I'm looking for the places that need to be touched, but that wouldn't occur to me (and maybe not to an AI either) while I'm knee-deep in the code. Seeing where the AI touched isn't going to solve that.

Re: How to write an effective software design document

#76

Post by mtlynch »

cowthulhu wrote: post #45

I was initially turned on to the idea of using specs by Joel Spolsky [ https://www.joelonsoftware.com/2000/10/02/painless-functiona... ] 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 ca…

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

Re: How to write an effective software design document

#77

Post by dropofwill »

jimbobimbo wrote: post #7

My problem recently is to have people read design docs I'm writing.

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

Re: How to write an effective software design document

#78

Post by lopatin »

tra3 wrote: post #70
lopatin wrote: post #62

Earlier quoted context omitted.

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

I think it's worth more scrutiny today, rather than less. Your claude code can barf out "a rewrite" but is it any good? So far the answer is "no" (see anthropic's C compiler, or a more recent port of bun). Software is still the best specification for existing behavior..

I'm not following because a) The bun rewrite was a success b) the C compiler wasn't a rewrite and c) "Software is still the best specification for existing behavior" seems to imply that rewrites are achievable because we already have a working version that functions as a spec?

Re: How to write an effective software design document

#79

Post by barrkel »

mtlynch wrote: post #71
barrkel wrote: post #63

Earlier quoted context omitted.

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…

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

I'm not suggesting using AI generated code as a proposed design.

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.

Re: How to write an effective software design document

#80

Post by mtlynch »

vjvjvjvjghv wrote: post #49

The real question is "How to keep a software design document up-to-date". I have never seen this done in an efficient way. The first version is ok and over time it deviates more and more from reality. 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.

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

Post reply on HN