4 ms·

It's making blanket assumptions that a) the question asker knows better, and b) that no one bothered to think of any of this to begin with. That's not a functio

It's making blanket assumptions that a) the question asker knows better, and b) that no one bothered to think of any of this to begin with. That's not a functional way to approach organizational problems like teams building the wrong thing. Never mind that, I'd wager oftentimes the IC standing up a new repo isn't the right tree to bark up anyway. FWIW, I personally start new projects with a Software Design Intent document that explains what we're attempting to do and why with full disclaimers about what we do and don't currently know. Maybe I've just managed to hedge these people out.

sowbug 3y ago
> Software Design Intent document That's great. But having written it doesn't mean that everyone has read it. And not everyone who has read it will agree with it. Or maybe the person who you thought would champion it has left the company. Or maybe the world has changed since you wrote it. You've probably heard the expression "no business plan survives first contact with customers." A corollary, in anything but an extremely top-down organization, is that version 1 of your planning doc is unlikely to perfectly describe the final product. > a) the question asker knows better, and b) that no one bothered to think of any of this to begin with Eh, that's assuming a fair amount of antagonism on both sides. Most people are reasonable and rational, and after the initial "WTF? Are you crazy?" handshaking, everyone can get on the same page. But that process takes time. If your first contact with a downstream person/team/group is right before your 1.0 is supposed to ship, then you're more likely to treat them as a roadblock. If you instead involve them early, get the WTF moments out of the way, and take the time to develop a relationship, then you've turned a potential roadblock into a stakeholder and advocate, and your SDI becomes a true representation of consensus, rather than a bludgeon.
- scruple 3y ago
  > That's great. But having written it doesn't mean that everyone has read it. It's just describing the intention of the team at the onset. Nothing more. I will not update this document once things get really rolling, that's why we have design documents elsewhere. What I personally do with this thing is I put a checklist of "approvers" at the bottom and I send an e-mail to them all asking them to review it and give their nod of approval or otherwise. FWIW I'm in agreement with everything else you're saying here, though.
RetroTechie 3y ago
> Software Design Intent document Sounds like a good way to nip the creative aspect in the bud. Sure, if a client comes to a software vendor with a clear plan, draw up good specs, requirements etc. before doing any design (or coding). Or code a quick 'n dirty proof of concept solely to hash out what exactly those requirements are. Same with existing codebase if you want to add feature X and scope of that is well defined. But I suspect quite a few applications / projects / websites / tech startups / software libraries have started life with a "hey, that's neat. Let's take X, glue onto Y, tinker & play with it, see what we can do with that". Small / cheap 1st iterations don't involve much wasted effort anyway. Worst case = 0 useful code but you have learned something. When utility has shown & you get a sense of where you want it to go, then bring in the design aids for a proper v1.x, 2.x etc.
warrenm 3y ago
>that no one bothered to think of any of this to begin with. That's not a functional way to approach organizational problems like teams building the wrong thing The odds you're the first one to have thought of something are [practically] zero The odds you're the first to implement something are only slightly higher When you find out someone else has already built 89% of what you're looking for (and 213% of what you hadn't thought of yet, because they already ran into the corner cases and what-ifs you couldn't possibly have thought of until you hit them), you can save yourself (and the organization) loads of effort by extending what's there instead of building from scratch Maybe you're the first to think of it and first to build it But you're probably not - and getting that early feedback from someone who sees what you're working, and says, "why are you building what Sally & Tom built last spring?" is absolutely invaluable

sowbug 3y ago

> Software Design Intent document That's great. But having written it doesn't mean that everyone has read it. And not everyone who has read it will agree with it. Or maybe the person who you thought would champion it has left the company. Or maybe the world has changed since you wrote it. You've probably heard the expression "no business plan survives first contact with customers." A corollary, in anything but an extremely top-down organization, is that version 1 of your planning doc is unlikely to perfectly describe the final product. > a) the question asker knows better, and b) that no one bothered to think of any of this to begin with Eh, that's assuming a fair amount of antagonism on both sides. Most people are reasonable and rational, and after the initial "WTF? Are you crazy?" handshaking, everyone can get on the same page. But that process takes time. If your first contact with a downstream person/team/group is right before your 1.0 is supposed to ship, then you're more likely to treat them as a roadblock. If you instead involve them early, get the WTF moments out of the way, and take the time to develop a relationship, then you've turned a potential roadblock into a stakeholder and advocate, and your SDI becomes a true representation of consensus, rather than a bludgeon.

scruple 3y ago
> That's great. But having written it doesn't mean that everyone has read it. It's just describing the intention of the team at the onset. Nothing more. I will not update this document once things get really rolling, that's why we have design documents elsewhere. What I personally do with this thing is I put a checklist of "approvers" at the bottom and I send an e-mail to them all asking them to review it and give their nod of approval or otherwise. FWIW I'm in agreement with everything else you're saying here, though.

RetroTechie 3y ago

> Software Design Intent document Sounds like a good way to nip the creative aspect in the bud. Sure, if a client comes to a software vendor with a clear plan, draw up good specs, requirements etc. before doing any design (or coding). Or code a quick 'n dirty proof of concept solely to hash out what exactly those requirements are. Same with existing codebase if you want to add feature X and scope of that is well defined. But I suspect quite a few applications / projects / websites / tech startups / software libraries have started life with a "hey, that's neat. Let's take X, glue onto Y, tinker & play with it, see what we can do with that". Small / cheap 1st iterations don't involve much wasted effort anyway. Worst case = 0 useful code but you have learned something. When utility has shown & you get a sense of where you want it to go, then bring in the design aids for a proper v1.x, 2.x etc.

warrenm 3y ago

>that no one bothered to think of any of this to begin with. That's not a functional way to approach organizational problems like teams building the wrong thing The odds you're the first one to have thought of something are [practically] zero The odds you're the first to implement something are only slightly higher When you find out someone else has already built 89% of what you're looking for (and 213% of what you hadn't thought of yet, because they already ran into the corner cases and what-ifs you couldn't possibly have thought of until you hit them), you can save yourself (and the organization) loads of effort by extending what's there instead of building from scratch Maybe you're the first to think of it and first to build it But you're probably not - and getting that early feedback from someone who sees what you're working, and says, "why are you building what Sally & Tom built last spring?" is absolutely invaluable