3 ms·

> I turned our product from a total waste about to be cancelled into a promising tech with some momentum, but I spent all my time coding instead of writing abou

> I turned our product from a total waste about to be cancelled into a promising tech with some momentum, but I spent all my time coding instead of writing about coding, and I likely won’t get promoted again this cycle. As a FAANG SWE, what I am reading is "I spent two years cranking out code without doing any design work. My manager and TL never suggested I write a design doc, or didn't give me opportunities to do so." At least at my employer - where, yes, you typically need to do design work to get promoted - that shouldn't happen. It's a failure of management if it did.

lostcolony 5y ago
Designing != documenting design. To get promoted in FAANG (and many large tech companies), yes, you need to document it. Interestingly, whether it works or not is completely unrelated to whether it's documented or not. In fact, the types of useful documentation (descriptions of how decisions were reached, known tradeoffs, API contracts, etc) often are completely different than the types of documentation management asks for (box diagrams that no one but management looks at). And the timeline for generating it is often different as well (management oftentimes asks for documentation before implementation, where such documentation runs the risk of being an incorrect blueprint; what is useful is documenting along the way). Valuing documentation can be done well, but pretty much every place I've seen it as an organizational requirement it has been a checkbox (and definitely running afoul of the agile manifesto, which makes it doubly frustrating, when an org also says "we're agile because we do scrum" or whatever).
- allturtles 5y ago
  > Interestingly, whether it works or not is completely unrelated to whether it's documented or not. I disagree. Writing up your design gives others the opportunity to provide feedback and improve the design (and possibly catch major flaws) before you build it. If you never write up your design there's a higher chance that you have built something that doesn't correctly fulfill the product requirements / won't scale / will fail under some race condition you didn't anticipate / is not compatible with the plans an adjacent team has to touch the same area in the next 6 months / etc.
  - lostcolony 5y ago
    I think you're assuming that documentation is the only way to collaborate. I'm a big fan of talking to people. The outcome of that talking may turn into documentation, but, per my post, it tends to turn into -useful- documentation if it does, which is very different than the company mandated types of documentation, at least in my experience. A software specific formulation of Goodhart's Law applies here; if documentation is the metric, the organization will prioritize documentation, regardless of its effect on delivery. If working code is the metric, documentation may still happen if it helps to deliver working code. There have been zero times that mandated documentation felt helpful to me, and was able to be used without massive modification after the fact by anyone else (I remember one project that had their architectural design document v1...and v2. v1 was the mandated "before you build", and v2 was the "we've now built something that works and it is so different that it's easier to start anew than modify v1"); there have been uncountable times that I have chosen to document something that seemed important to share or persist to inform later decisions.
    - allturtles 5y ago
      > if documentation is the metric, the organization will prioritize documentation, regardless of its effect on delivery. If working code is the metric, documentation may still happen if it helps to deliver working code. IMO, good organizations should have both metrics. You should document your intent, and then you should be able to show that it worked out after the fact. "Working code" is a lagging metric with many dimensions (functional, secure, performant, etc.). If your only reason to believe you will get to working code on all those dimensions on a 6 month+ project is that the person who is building it thinks it's right, that's a big risk. It seems like you're describing a particular kind of dysfunctional org where there's top-down mandates for forms of documentation that aren't valuable for sharing plans or informing later decisions. That hasn't been my experience of how design is done where I've worked, where writing designs is a collaborative process that starts with your team.
    - joshuamorton 5y ago
      > I'm a big fan of talking to people. The outcome of that talking may turn into documentation, For any nontrivial design, it must. I expect that many people in this thread are coming from the Google (or Amazon?) perspective where a "design doc" is a formalization of a collaborative conversation. For small designs, it may be just a mild reformation of a set of meeting notes (you should take notes when you talk to people!). For larger projects, there's an iterative process where you start with a proposal that may be that, and get it reviewed and ensure you cover all the aspects that it will impact. I've been on both he giving and receiving end of the "oh hey you may need to rethink this due to XYZ" at what was assumed to be late in the design process. THat's annoying, but much less annoying than spending 2 weeks or 2 months building a thing only to have to throw that effort away.
- endtime 5y ago
  > Designing != documenting design. At least at Google (where I work), a "design doc" is an iterative and interactive design proposal, including alternatives considered and rationale for design choices made, not (just) documentation of what the design is. "Documentation" of the sort you describe is an almost entirely unrelated thing, again just speaking of Google.

lostcolony 5y ago

Designing != documenting design. To get promoted in FAANG (and many large tech companies), yes, you need to document it. Interestingly, whether it works or not is completely unrelated to whether it's documented or not. In fact, the types of useful documentation (descriptions of how decisions were reached, known tradeoffs, API contracts, etc) often are completely different than the types of documentation management asks for (box diagrams that no one but management looks at). And the timeline for generating it is often different as well (management oftentimes asks for documentation before implementation, where such documentation runs the risk of being an incorrect blueprint; what is useful is documenting along the way). Valuing documentation can be done well, but pretty much every place I've seen it as an organizational requirement it has been a checkbox (and definitely running afoul of the agile manifesto, which makes it doubly frustrating, when an org also says "we're agile because we do scrum" or whatever).

allturtles 5y ago
> Interestingly, whether it works or not is completely unrelated to whether it's documented or not. I disagree. Writing up your design gives others the opportunity to provide feedback and improve the design (and possibly catch major flaws) before you build it. If you never write up your design there's a higher chance that you have built something that doesn't correctly fulfill the product requirements / won't scale / will fail under some race condition you didn't anticipate / is not compatible with the plans an adjacent team has to touch the same area in the next 6 months / etc.
- lostcolony 5y ago
  I think you're assuming that documentation is the only way to collaborate. I'm a big fan of talking to people. The outcome of that talking may turn into documentation, but, per my post, it tends to turn into -useful- documentation if it does, which is very different than the company mandated types of documentation, at least in my experience. A software specific formulation of Goodhart's Law applies here; if documentation is the metric, the organization will prioritize documentation, regardless of its effect on delivery. If working code is the metric, documentation may still happen if it helps to deliver working code. There have been zero times that mandated documentation felt helpful to me, and was able to be used without massive modification after the fact by anyone else (I remember one project that had their architectural design document v1...and v2. v1 was the mandated "before you build", and v2 was the "we've now built something that works and it is so different that it's easier to start anew than modify v1"); there have been uncountable times that I have chosen to document something that seemed important to share or persist to inform later decisions.
  - allturtles 5y ago
    > if documentation is the metric, the organization will prioritize documentation, regardless of its effect on delivery. If working code is the metric, documentation may still happen if it helps to deliver working code. IMO, good organizations should have both metrics. You should document your intent, and then you should be able to show that it worked out after the fact. "Working code" is a lagging metric with many dimensions (functional, secure, performant, etc.). If your only reason to believe you will get to working code on all those dimensions on a 6 month+ project is that the person who is building it thinks it's right, that's a big risk. It seems like you're describing a particular kind of dysfunctional org where there's top-down mandates for forms of documentation that aren't valuable for sharing plans or informing later decisions. That hasn't been my experience of how design is done where I've worked, where writing designs is a collaborative process that starts with your team.
  - joshuamorton 5y ago
    > I'm a big fan of talking to people. The outcome of that talking may turn into documentation, For any nontrivial design, it must. I expect that many people in this thread are coming from the Google (or Amazon?) perspective where a "design doc" is a formalization of a collaborative conversation. For small designs, it may be just a mild reformation of a set of meeting notes (you should take notes when you talk to people!). For larger projects, there's an iterative process where you start with a proposal that may be that, and get it reviewed and ensure you cover all the aspects that it will impact. I've been on both he giving and receiving end of the "oh hey you may need to rethink this due to XYZ" at what was assumed to be late in the design process. THat's annoying, but much less annoying than spending 2 weeks or 2 months building a thing only to have to throw that effort away.
endtime 5y ago
> Designing != documenting design. At least at Google (where I work), a "design doc" is an iterative and interactive design proposal, including alternatives considered and rationale for design choices made, not (just) documentation of what the design is. "Documentation" of the sort you describe is an almost entirely unrelated thing, again just speaking of Google.