How to Write an Effective Software Design Document(refactoringenglish.com)
3 pointsby mtlynch2 hours ago2 comments
  • blinkbat2 hours ago
    The example app is making me upset... Instagram redux? Why
    • mtlynch2 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...

      • blinkbat2 hours ago
        wouldn't these small groups just like... send an email? group chat?
        • mtlynchan hour 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/

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

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