How to Write an Effective Software Design Document

https://refactoringenglish.com/excerpts/write-an-effective-design-doc/

by mtlynch • 28 days ago

4 8 28 days ago

blinkbat2• 28 days ago

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

mtlynch3• 28 days 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...

blinkbat2• 28 days ago

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

tylerhackbart• 28 days 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.

mtlynch3• 28 days 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.

nkdSecurityLabs2• 26 days ago

Should permission handling, battery optimization, and foreground service behavior be included in the design doc or left to implementation?

nkdSecurityLabs2• 26 days ago

How should you document Android-version-specific behavior (Android 6–16) without making the document difficult to read?

How to Write an Effective Software Design Document

Related Stories