How to Write an Effective Software Design Document

4 pointsposted 6 hours ago
by mtlynch
(refactoringenglish.com)

6 Comments

blinkbat

6 hours ago

The example app is making me upset... Instagram redux? Why

mtlynch

6 hours ago

It's for private photo sharing with family or close friends. It's more like an open-source, self-hostable TinyBeans or PhotoCircle. I explain the motivation more in the design doc:

https://refactoringenglish.com/excerpts/write-an-effective-d...

blinkbat

6 hours ago

wouldn't these small groups just like... send an email? group chat?

mtlynch

5 hours ago

The target audience of the app is me and my wife. This is a "home-cooked meal" app.[0] If it's useful to other people, I'm glad, but I'm primarily building it for myself for the pleasure of building and the satisfaction of a tool that works exactly how I want it to work.

You could approximate it with email, but I want things that you can't do with email like letting recipients control the frequency of emails, making high-res images available without bloating everyone's inboxes.

[0] https://www.robinsloan.com/notes/home-cooked-app/

tylerhackbart

6 hours ago

The "what's the penalty for being wrong" question is the part I'd keep. That one works at any scale.

But I spent five years on a solo app and never wrote anything close to this. Not on principle event, just the design just kept moving. The decisions that ended up mattering weren't ones I could have named on day one, they were things I cut in year three once I actually understood what the app was for. If I'd written the objective sentence up front I'd have locked in a version that turned out wrong. The clarity came from building the thing, not from describing it first.

For coordinating people or catching a security flaw before it ships, sure, all of this makes sense. Solo just runs on different rules I guess.

mtlynch

5 hours ago

Thanks for reading!

>But I spent five years on a solo app and never wrote anything close to this. Not on principle event, just the design just kept moving.

Yeah, I agree that for solo projects, it makes sense to greatly scale down the design phase. In a lot of cases, you'd scale design down to zero if you need user feedback to figure out what to build.

But even for solo projects, if I keep at it for months or years, I eventually get to the point where some problem is hard enough that I need to do some upfront design, even if it's not as formal as a whole design doc.