[HN Gopher] Design docs at Google (2020)
___________________________________________________________________
Design docs at Google (2020)
Author : BerislavLopac
Score : 294 points
Date : 2024-05-06 11:54 UTC (1 days ago)
(HTM) web link (www.industrialempathy.com)
(TXT) w3m dump (www.industrialempathy.com)
| leoh wrote:
| Does anyone know where to find a copy of go/greendoc?
| lrem wrote:
| Why would you? If you feel the process is worthwhile
| replicating elsewhere, just use your own words for the couple
| paragraphs of instructions.
| leoh wrote:
| I don't even really remember what the sections were any
| longer
| danpalmer wrote:
| There's almost nothing in the greendoc template, I'm not sure
| it's at all valuable outside of Google.
| leoh wrote:
| I worked at Google and respectfully disagree
| runeblaze wrote:
| It is useful but at the same time different teams IIRC had
| different design doc structures. I was overwhelmed by
| go/greendoc when I was an intern and I just opened an empty doc
| and started writing based on my team's existing design docs...
| and that worked better. In the end it is just technical
| writing.
| yareal wrote:
| Design docs are great, but Google's writing culture is highly
| fragmented and quite disjointed. I much prefer Amazon's writing
| culture (despite hating absolutely everything else about Amazon's
| culture.)
| bushbaba wrote:
| Amazon uses writing to bias for action in meetings. Their
| culture has DRIs (or dictators) who have authority to make the
| call, with such authority coming with some level of
| accountability to the decision made. At Amazon the doc is read,
| parties discuss, and decision made. At Google the doc is rarely
| entirely read, mostly commented on, and no decision made until
| all stakeholders align on a commonly agreed direction.
|
| The amazon way is much less toxic, but does come with a need
| for writer to invest heavily on a high quality doc. Personally,
| the Amazon way is better but only works due to their peculiar
| culture.
| spondylosaurus wrote:
| Amazon has famously high turnover, doesn't it? I wonder how
| much their investment in docs is downright critical to
| keeping the ship afloat--otherwise people leave and take all
| their knowledge with them. But if it's written down you can
| pass the torch.
| iLoveOncall wrote:
| After working there for 6 years, I haven't seen a single up
| to date design doc. At best a high level diagram.
|
| They are outdated as soon as implementation start, by
| different degrees depending on the project.
|
| Side note but I think this average tenure number hasn't
| been updated in a very long time. In London for example, a
| third of employees have been here for more than 5 years.
| dbish wrote:
| US (where bulk of employees are) is still pretty close to
| 2 years unless that changed a lot in just a few years (I
| was a sr. dev manager there and worked there for around
| 6.5 yrs). This is pretty similar to the rest of big tech
| though except for Microsoft. England and Europe in
| general is a bad comparison since they have fewer options
| and very different working expectations.
| underdeserver wrote:
| That wasn't my experience at Google. We would consistently
| start work in parallel to getting our design docs reviewed,
| maybe waiting a day or two for the first batch of comments.
|
| You could usually tell which parts are not going to be
| controversial and start with those.
| faizshah wrote:
| This highly depends on team and project. The more ambiguous
| your project is the more likely no decision will be made and
| you will instead need to commit to a follow-up meeting with
| more docs and more people.
| dbish wrote:
| Yes the design by committee will continue until morale
| improves.
| dbish wrote:
| Those are usually called STOs for people who make the final
| call, not DRIs, from what I saw in my tenure there. The
| Amazon doc is a great concept when there are single threaded
| owners, however Amazon also has had culture and growth issues
| where "alignment" (like Google) became more important as team
| and orgs grew with multiple doc "owners" in direct
| contradiction of what Bezos used to preach so it just becomes
| design by committee for new features and products. Org
| dependent of course but I think that was the Day 2 culture
| seeping in as Bezos moved on and the company grew.
| jongjong wrote:
| This is a great habit. I wish all projects had a coding style
| document. Coding philosophy is much more important than tooling
| and choice of languages IMO. Not having such style guide is like
| employing builders on a construction project without letting them
| see the plan.
|
| That said, about this point:
|
| - Ensuring consideration of cross-cutting concerns.
|
| My answer would be "Avoid cross-cutting concerns because they are
| a violation of the separation of the concerns principle; a
| violation of the cross-cutting kind" ;p
|
| My observation is that while avoiding cross-cutting concerns can
| seem challenging at first, creating a code architecture which
| avoids them leads to much more maintainable and easy to follow
| code. I've worked on many complex projects; distributed systems,
| blockchains, P2P messaging systems... but I'm yet to encounter a
| project which cannot be structured in a way to avoid cross-
| cutting concerns completely.
|
| That said, IMO, aspects mentioned in the article like "security,
| privacy, observability" aren't really separate 'concerns' but
| merely desired characteristics of software components.
| dpe82 wrote:
| Perhaps read the section dedicated to this point:
| https://www.industrialempathy.com/posts/design-docs-at-googl...
|
| Some cross-cutting concerns are about more than just code, but
| things like "how will you monitor this for reliability?" or
| "this system reads user-sensitive data, how will those reads be
| audited?" and so on. Usually the answer is short: "use standard
| system xyz" - but having it there and ensuring it's followed
| through on are important.
| jongjong wrote:
| Fair enough. Definitions can be broad. The term "Cross-
| cutting concerns" made me think of aspect-oriented software
| development which has a very specific definition and it tends
| to favor specific approaches like dependency injection.
|
| For example, in aspect-oriented development, they tend to
| promote injecting a logger into all the components; but other
| development methodologies might instead make it so that
| messages and errors bubble up the component tree (e.g. for
| non-error messages, might use event emitters, message
| passing, callbacks, or other kinds of channels). But the idea
| is that the messages for all components are aggregated,
| handled and logged near the top level in a central place; so
| you don't need to inject a logger instance into every
| component; it loosens the coupling of your components with
| the rest of your application... Also, logging might be just
| one of things you do with those messages.
|
| It's nice to have that logic near the top level of the code.
| I find it extremely valuable when the important outputs of
| the system (what the developer or user can physically
| observe) can be traced starting from a single source file (or
| at least, as few files as possible).
| s17n wrote:
| I feel like at Google, design docs suffer from being the main
| thing that goes in your promo packet, which leads to the writing
| being done more with promo committee in mind then the documents
| ostensible audience of people who are working on the system the
| document pertains to.
| underdeserver wrote:
| I'm not sure what the difference is, except giving more context
| than teammates need, or trying to make a problem more complex
| than it is.
|
| By and large I didn't notice that strategy working.
|
| On the other hand, for context, people wrote large docs on what
| the team did and does, what the problems are, etc. and those
| did tend to be long and exaggerated.
| dietr1ch wrote:
| This makes many docs follow the pattern of a more complex
| design when its completely unnecessary. All just to get more
| "perf points" from the people that only have time to skim
| through the docs.
|
| I read many docs that, to me, obviously made up a decision and
| showcased the thing we already wanted by the time the doc was
| started, and 2+ silly alternatives (at least one way too simple
| and an unnecessary overkill) and contrasted them to pick the
| thing that was reasonable.
| kaon_ wrote:
| True for every employer i've ever been at. Your career is
| mostly steered by exposure, rather than reputation or ability.
| Design docs are very visible to those above you. At yvery
| company I join, I propose we start writing design docs. It
| immediately puts me in good standing with management :)
| r0ze-at-hn wrote:
| Devs straight up tell you that they write design docs for the
| promo committee. That is their goal, everything else is
| secondary. Given that they never know which design docs they
| will use in their promo packet they put everything they work on
| in design docs no matter how small. There is the idea of a one
| pager design doc, but usually they grow from one page to ...
| many. It might be a one week project, but a design doc gets
| written. I have also had to reviewed 20, 30, even 40 page
| design docs that took clearly a while to make and at any other
| company would be simply a JIRA ticket. I have had discussions
| about how many pages is too many and if we should have a limit
| etc.
|
| Too many have learned (correct or not) that promo committees
| want to see that _only_ the author wrote a doc and no one else.
| This further slows down everything and disincentivizes cross
| learning. I know software engineers who spend a full quarter or
| more in isolation writing design docs. The majority of the
| writing in a design doc is the actual design, but the other 99%
| is the definition of the problem. Too many times I have been in
| a review and spent a bunch of time improving the definition of
| the problem which results in the design needing to be scrapped
| and most of the doc needing to be re-written.
|
| Worst case scenario is when by improving the problem definition
| a simple solution appears that doesn't require a complex
| design. The author having invested a lot of time in a complex
| design (that historically and many committees still look for to
| promote off of) will push back against anything that is simple.
| The difficult trick is helping the engineers to improve their
| problem definition early in the writing process.
|
| I have seen design docs that have no alternatives presented.
| The design doc was simply a labor intensive way to write down
| what needed to get done or what someone wanted to do.
|
| This also results in design docs turning into a bug tracking
| system if you squint. In a hand wavy way everyone is working on
| their design doc, not bugs, bugs can't get you promoted.
|
| And OP like to wax poetically about how when you join a team
| you can just go and look at the design doc like that is a
| simple and obvious thing. They are often not tracked in any
| central place. For many teams design docs are not owned by the
| team or the project, but by the individual because you can make
| sure no one else contributed. This is again for the promo
| committee sake. Many design docs you can't get access to, not
| because they are super secret, but just because. And it isn't
| like teams have say two or three design docs, no there is a
| mountain of design docs to read. And with around a two year
| turn over at Google many design docs get lost to time. At any
| other company this could be like if you joined the team and I
| said everything you need can be found by reading all the closed
| bugs or read every commit message in the main branch.
|
| Anywhere else I would have been grabbed after lunch and would
| have worked on defining the problem for a few hours with the
| team at the whiteboard. The senior members teaching the younger
| in real time how to think about these things and iterating
| quickly. Most of the time this would be written down in the bug
| tracking system or for bigger stuff in the project's
| wiki/folder to be owned by all.
|
| All of the above can be improved and I have worked on improving
| all of them, but culture is a slow thing to change. Design docs
| are a good idea as a concept, but there are pitfalls and the
| way they are being used by many (not all!) at Google is not it.
| larsrc wrote:
| > Worst case scenario is when by improving the problem
| definition a simple solution appears that doesn't require a
| complex design. The author having invested a lot of time in a
| complex design (that historically and many committees still
| look for to promote off of) will push back against anything
| that is simple. The difficult trick is helping the engineers
| to improve their problem definition early in the writing
| process.
|
| The worst case is really when even more time has been spent
| coding, testing, releasing, and integrating the overly
| complex design, and then it's extra work on top to get rid of
| it.
|
| > Anywhere else I would have been grabbed after lunch and
| would have worked on defining the problem for a few hours
| with the team at the whiteboard.
|
| I do that at Google regularly, often in parallel with writing
| the doc. Nothing beats talking with an experienced engineer
| directly.
| trelane wrote:
| That, and to comply with bureaucratic requirements. And
| commenting on others' docs, to "show leadership."
|
| I long for design docs that are worth more than their cost.
| dudus wrote:
| And on the product side you have product requirement docs which
| was always useful when a new feature came up as it aggregated all
| contacts, documentation, support, communications, etc. You always
| want to work in a product that maintains a decent one.
| smokel wrote:
| > _You always want to work in a product that maintains a decent
| one._
|
| That'd be lovely indeed. I have never seen one that I felt
| comfortable with, though. And I've seen a few.
|
| When LLMs rose in popularity, I had hopes of having a way to
| tackle the problem of formulating requirements in a way that
| would be less painful than it is now.
|
| To me, computer programming is a form of communication, where
| the requirements are close to humans, and program code is
| nearer to the machine. On the computer side, we have linters,
| compilers, and a deterministic system that executes the code.
| On the human side we have people stating requirements such as
| "The system should be easy to use."
| _obviously wrote:
| Remember, Google retains the right to copy databases as they're
| not copy protected.
| SSchick wrote:
| Design doc culture at google is why I left the company.
|
| I wrote a very high level doc shortly after joining the company
| outlining a fairly trivial task (one that has been performed many
| times across other product areas).
|
| A colleague virtually took me aside and told me "this is not how
| we do things here". Which was kind of a wake up call as he told
| me to make sure to 'evaluate many more ways to get this done'
| despite the way I outlined literally being a slight variation on
| the recommended way.
|
| When questioned about why this would be needed he said "it shows
| broad consideration".
|
| "Fake work" is very much a thing at google, I wish I joined a
| different team.
| devjab wrote:
| You have a point in that bureaucracy can needlessly get in the
| way of meaningful change. It frankly always will to some
| degree. That being said, part of the way you make sure it gets
| the least amount of in the way is to standardise it, and
| actually enforce those standards.
|
| From your description you fall into both categories, which
| means your colleague was correct. Now, your amount of details
| is very scarce, so it's extremely likely that I'm getting the
| situation wrong. But look at it from an enterprise level
| perspective or change management, if you allow slight
| deviations here and there for thousands of employees then
| you'll very quickly end up with what would be the equivalent of
| the difference between Italian, Spanish and French. Which all
| shares the same Latin "standard" and then deviated ever so
| slightly.
|
| If you think there is a lot of pseudo work involved with
| managing the bureaucracy of enforcing a design doc standard
| then you should see just how much pseudo work it saves.
| SSchick wrote:
| I don't disagree, hence "fake work" in quotes.
|
| Some people may (and clearly do thrive) in such environments
| but I personally did not.
|
| This particular scenario was a simplified excerpt but very
| well captures my perceived experience. Having to write a
| design for for something that was a solved problem (by a team
| maintaining a framework) felt like pure busy work.
|
| If there was a higher meaning to this process this higher
| meaning (other than looking good / getting promoted) was not
| communicated in any effective manner.
|
| Maybe I'm dis-illusioned with the current culture in big-tech
| but a promotion should be a result of doing good work, not
| doing work that is designed to look good.
|
| And yes I understand that some of these mechanisms may exist
| to provide employees a clearer path for ascending the
| corporate ladder.
| Degorath wrote:
| Sad to hear your team was like that, mine definitely went
| the way of "if you know which way you're going to solve a
| problem anyway, why bother writing a design doc?" and I
| never felt burdened by them.
| Lutger wrote:
| Good work needs to look good in order to be seen. And in
| enterprise, it needs to be able to be compared in order to
| be fair and afford some level of control from top down.
|
| Standards solve those problems at the cost of some overhead
| and waste, due to being what they are: a fairly generic
| reification of best practice (at best).
|
| Even though some overhead is just inherently part of the
| game, the efficacy of standards (and metrics) does vary.
| Not all have equal merit. And it does sound like some of
| the Google standards went off the rails a bit.
| devjab wrote:
| Oh I'm not a big fan of it either. Especially because I've
| never really seen a lot of the "fake work" have much value.
| Usually enterprise architecture or whatever you want to
| call it ends up being an insane amount of aged
| documentation that is useless because it's never updated
| despite the best intentions. Over the years it'll typically
| also erode its own standards as the people leading the
| efforts change and their standard preferences change with
| them.
|
| Last but not least, it's a total waste of time to have
| actual developers do it. Instead of working on something
| useful. Of course the challenge then becomes that 90% of
| the architects and whatever actually don't know how to
| write their own design documents from changes, which means
| they need to waste developer time to do it... meaning that
| no only are they a completely useless employee they are
| also wasting the time of useless employees.
|
| This shouldn't be taken as black and white. As I wrote
| earlier, it can be done to help work flow. It's just than
| in reality these processes usually end up doing far more
| harm than good. But if you, are, going to do it, at least
| enforcing standard is the right thing to do.
|
| I personally avoid working at places with too much
| bureaucracy because I don't want to waste my time writing
| documents nobody will ever read after they are approved.
| kortilla wrote:
| What you said would make sense if they weren't forcing the
| author to go find more alternative approaches.
| larsrc wrote:
| > You have a point in that bureaucracy can needlessly get in
| the way of meaningful change.
|
| What a good early design doc can do is turn meaningless
| changes (e.g., doing a project for the sake of promo) into
| meaningful non- or minimal change. The best code is the one
| not written.
|
| And at least in my area (Core), the design docs only go
| through anything like a formal process when it's a larger
| project that would take years or multiple engineers. Other
| areas are probably different.
| gonzo41 wrote:
| The old school way of fixing that problem is to have a standing
| change order for routine work so you can point to it and say
| "my problem is just like that" and get the green tick right
| away. Though the moment you suggests things like change control
| people get all weird these days.
| dyauspitr wrote:
| Then include templates from other areas pointing out the
| repeated work. You can't just hand off a couple of lines in a
| brief to a dev, especially if they are not aware it's been done
| before.
| t8sr wrote:
| You get the behavior you incentivize. In the "early days",
| design docs were a tool to agree on a direction and provide
| context to your coworkers about what you're doing. Later, as
| new people joined at an exponential rate, they were told by
| well meaning managers to write the docs for perf reasons, and
| things kind of spiraled from there. Google's culture became a
| cargo cult of itself.
|
| Some companies I worked at after Google were reluctant to
| discuss their promotion process in detail, because they saw
| what happens when people microoptimize for it.
| Arainach wrote:
| Microoptimizing for what the cargo cult believes gets you
| promoted is strictly worse than microoptimizing for what
| actually gets you promoted.
| klabb3 wrote:
| It's a meh from me - either is bad. If you are in a highly
| complex and professional field (in the traditional sense of
| the word) single axis optimization hollows out the whole
| craft. Engineering is delicate and constant battling of
| tradeoffs, and decision consequences are often delayed by
| longer than average tenure, let alone a 6 month perf cycle.
| The more you McKinsey the process, the more mediocre and
| incoherent the results.
| Arainach wrote:
| You get what you measure. You can't hire smart motivated
| people and then be surprised when they figure out to
| optimize for their rewards.
|
| If you want a team that lands stable customer-loved
| products, make THAT your performance review. Turns out
| that's hard to do objectively and consistently.
| lupire wrote:
| According to your other comment, then, a company that
| "lands stable customer-loved products" would be a "hotbed
| of nepotism" that people shouldn't work for.
| Arainach wrote:
| Nonsense - you can have documented metrics which are
| known and tied to performance.
|
| For example:
|
| * Require features to be launched for a period of time
| rather than in development or shoved out the door a week
| before perf
|
| * Have metrics for customer satisfaction and oncall pages
| be incorporated
|
| Etc.
| aprdm wrote:
| Nonsense were a lot of your replies in my experience :),
| this "measure everything" is very much another cargo
| cult. Software engineering is complex, people are
| complex, thinking you can come with a true metric and who
| doesn't have it doesn't know what they're doing is the
| nonsense in my world view.
|
| Have excited engineers, pay them well, have them work on
| something that is aligned with their career & deliver
| value to their customers, they don't really need much
| more than that. All the rest is simply trying to
| "processi-ze" what is a human
| klabb3 wrote:
| > You can't hire smart motivated people and then be
| surprised when they figure out to optimize for their
| rewards.
|
| Never said that. I don't have a solution. Well I have a
| partial solution, but not complete:
|
| Reward all team members equally for the performance of
| the team, or even the company. For instance: the pie is
| divided into 3 pieces: company, team, and individual
| performance. Candy is given out based on performance of
| both.
|
| It doesn't fix the hackable metrics issue, but when
| people collaborate the side effects are better than when
| they think of their own promotions, and worse when
| they're competing against their direct peers for a fixed
| bucket of candy per team. Such incentives are directly
| opposing collaboration between the very people that need
| to collaborate the most.
| JustLurking2022 wrote:
| At some point, the cargo cult are the promo reviewers and
| then the two become the same thing.
| Arainach wrote:
| The reviewers presumable have access to the true metrics.
| trelane wrote:
| What if I told you these _are_ their "true metrics?"
| Arainach wrote:
| If a company doesn't have consistent metrics for
| performance reviews uniformly across teams, get out of
| that company yesterday. That's just a hotbed of nepotism.
| lupire wrote:
| Please give an example of a metric for performance review
| for software engineering.
| Arainach wrote:
| Conceptual examples (not looking to argue about the
| specific bar):
|
| Senior engineers will:
|
| * Design a significant project which lands with
| measurable customer impact
|
| * Demonstrate expertise in at least one core skill
| outside of coding (test infrastructure, SRE, security,
| accessibility, etc.)
|
| * Demonstrate leadership by either being a TL, owning and
| leading team pillar efforts (security review, etc.), etc.
|
| * etc.
|
| Mid-level engineers will:
|
| * Own either a small feature end to end or a significant
| piece of a larger design
|
| * Contribute to at least one non-coding pillar
|
| * etc.
|
| These generally have more areas and can be further
| granular such as "low-performing midlevel is X,
| satisfactory is Y, exceeding is Z"
| dpe82 wrote:
| Those are requirements, not metrics.
| Arainach wrote:
| With sufficient granularity there is no difference. I
| can't give exact quotes without violating NDAs but
| variations on these have been the performance review
| standard at every major company I've worked at or known
| people who work at.
| mewpmewp2 wrote:
| What do you mean by "true metrics"?
| Arainach wrote:
| The metrics which determine if someone gets promoted.
| Those decisions are being made by some group, presumably
| with guidelines. If the process for getting promoted is
| "this group does whatever they feel like" that company is
| a disaster and you need to get out.
|
| Thus, there are rules, and they are written down. If
| they're not visible to normal employees, they guess the
| rules based on who they see get promoted (cargo cult)
| while the committee uses the true metrics.
|
| It's not like becoming a manager is a secret cult where
| you're dropped in and you suddenly have carte blanche to
| do anything. At established companies there are rules and
| procedures, and while you will likely have access to more
| information than individual contributors, you won't just
| be promoting whoever you feel like without having to go
| through others.
| racional wrote:
| Either way -- 'twould seem that if such a level of
| microstrategizing is what monopolizes one's attention on a
| day-to-day basis -- then one is definitely in the wrong
| place.
| tdb7893 wrote:
| When I was at Google I mentored a lot of early career
| engineers and I always told them to write more docs than they
| think they need. Sometimes docs will catch problems
| beforehand but early in the career writing easy docs is a
| simple way to show independence and competence. It slows down
| projects but Google is probably gonna cancel that project
| anyway and my theory was "Google doesn't care about you so
| caring about it just makes you a chump". It was in most ways
| a great place to work but it slowly drove me insane.
| mewpmewp2 wrote:
| But if they are going to cancel it anyway I would rather at
| least code and build just to have fun and at least have a
| prototype rather than doing the boring work. Also I feel
| like I can't get into right frame of mind of problem
| solving by writing a doc compared to if I am coding.
| rvnx wrote:
| If the project is anyway eventually going to be
| deprecated and shutdown, maybe it's better to take one of
| the Google bike and go round the campus drinking one of
| these tasty granitas from the cafeteria.
| mewpmewp2 wrote:
| Is there alcohol in it? If so, I would consider, but I
| would still take the alcohol and code the project as
| well.
| tdb7893 wrote:
| The craziest thing to me is that at my location not that
| many people did the free workout classes. Between those
| classes and the food I was in the best shape of my life
| while working there.
|
| I steadily got in better shape as they kept cancelling
| the projects I worked on and I slowly lost and sort of
| will to care about my actual job. The quality of my work
| ended up suffering a lot as I realized just how pointless
| trying to work there was for me but the pay was too good
| to want to leave.
|
| Edit: I was unlucky though. I knew some people with more
| stable projects. I went through 4 cancelled projects in
| close to 6 years
| tdb7893 wrote:
| If they like coding and didn't want to prioritize career
| advancement I would tell them to put effort into finding
| the projects (or parts of projects) they find more
| interesting to code and make sure they get assigned that.
| My advice was always personalized. The thing is that for
| most early career engineers they are already coding
| enough (and it's not like the code is generally
| particularly interesting) so most of the time the advice
| is to do more docs since the lack of docs was hurting
| them for perf/grad but it varied from individual to
| individual
| scottyah wrote:
| This sounds like you are championing the very mindset that
| has made google crumble?
|
| Write docs that slow things down, don't code/build
| projects, and do it all in the name of greed and the only
| justification is that it will get cancelled anyways
| (probably because no real work was being completed).
| tdb7893 wrote:
| I was just a cog in a machine. The mindset didn't come
| from me but how they setup incentives internally and ran
| projects. To be clear, I ended up really resenting how it
| works and the advice was based on my experiences with
| trying to care (in fact I'm trying to get out of tech
| entirely). I ended up channeling my care and effort into
| building up coworkers rather than into the company or
| it's products and that's how I got through it for a
| while. Different people had different experiences though
| (it's a huge company after all), anything I say about my
| experience is very personal.
|
| Edit: also if Google wanted me to really care about my
| job more than for self interest that relationship needed
| to be a two way street. The relationship of the devoted
| employee and disinterested company is common but to me
| comes across as a bit pathetic. I did a good job there
| purely because that's how I enjoy doing my job, if the
| company collapsed I wouldn't have shed a single tear
| (that's a lie, I miss the free food)
| larsrc wrote:
| Caveat: Googler here.
|
| One of the things that had been problematic at Google is
| the creation of many more products than are really
| needed, leading to the infamous Google Graveyard. One of
| the reasons I have come to like writing design docs for
| my ideas is that a lot of the ideas turn out to be crap
| when they get written out. Quite a few are good enough
| that they have already been done, or close enough, which
| my colleagues can then inform me of. This is a very
| lightweight way of trimming out useless projects.
|
| And no, Reader wasn't useless. Different story.
| thisisit wrote:
| I have a reverse problem at the place I work. When I ask people
| to write a very high level design doc for a fairly trivial task
| they go - "There many more way to get this done so writing
| these is useless. And as the task is trivial an engineer should
| be able to figure out one of these ways and do it."
|
| Many of these people are external consultants who have been
| working with the company for 15+yrs. So, there is a fair
| standard in place already because the tasks are done by the
| same people. But then they go out of their way trying to create
| a boogeyman of "what happens if people don't follow the
| standards?".
|
| The end result is that either design docs don't exist or
| woefully out of date. Hence the company has to keep hiring
| these same consultants year after year on hugely inflated
| costs.
| Cthulhu_ wrote:
| > Hence the company has to keep hiring these same consultants
| year after year on hugely inflated costs.
|
| There it is. There's good scratch to be made in prolonging
| the problem.
| jppittma wrote:
| We do "one-pagers" if there's basically one, simple, straight
| forward way to do something; however, I'm with google on this
| one.
|
| If you're designing something, and there's only a single
| solution under consideration, either there's no design, or
| you're not being thorough. Choices and tradeoffs are what make
| design
| mewpmewp2 wrote:
| What if it is something really obvious and has been done so
| for last 20/20 times it feels almost embarrassing to consider
| anything else? You could list out the embarrassing methods,
| but it still feels useless work for show.
| Jensson wrote:
| Then it is just a change and reviewed through normal code
| review. Design docs is only for when you do something that
| isn't obvious.
| mewpmewp2 wrote:
| But then you don't get promo?
| Arainach wrote:
| You don't get promo in your scenario either. A design doc
| for something that's trivial will be called out in promo
| packet review and not given much credence. If the packet
| is primarily comprised of such artifacts the promo will
| be denied.
| lupire wrote:
| It depends on level. For a junior, these are great design
| docs because they educate other juniors about
| engineering, and educate senior bad-doccers about good
| doc writing, and show developing skill in the art of doc
| writing, before the engineer has the additional cognitive
| burden of writing about something much harder.
| jppittma wrote:
| Do good non-doc-worthy work => Get doc-worthy work =>
| Write doc => Get promo
| masto wrote:
| I don't want to get sucked into defending Google-style
| design docs (I have.. opinions), but on this particular
| point a couple of things come to mind:
|
| 1. Presumably you've written the doc to be read by other
| people. What's obvious to you might not be obvious to them.
|
| 2. If you have no "alternatives considered", it's an
| indicator that you didn't consider any alternatives. I can
| think of times when "this is obvious and it's the way we've
| always done it" sent me down the wrong path. Spending just
| a couple of minutes considering whether obvious == correct,
| and writing down why, is not a bad investment in the long
| term.
|
| 3. I can only speak for myself, but I don't enjoy being
| criticized and I don't enjoy being wrong. "Alternatives
| Considered" is often at the end of the doc and I'm tempted
| to avoid it because there's a very real possibility that I
| will find the process of explaining why we don't just do
| option B instead leads to a realization that option B is a
| better alternative than the plan I just spent all that time
| on.
|
| 9/10 times it's short and easy, but it's still a worthwhile
| exercise for the reasons above. Explaining the "don't do
| anything" alternative is a good way to reinforce the
| cost/benefit of what you're proposing, and it's usually
| pretty easy to put yourself in someone else's shoes for a
| second and think of the first "but why don't you just" that
| will probably pop into their head. Write down "because it
| won't scale" and you've saved yourself that conversation.
| (joking. maybe.)
| aatd86 wrote:
| > I can only speak for myself, but I don't enjoy being
| criticized and I don't enjoy being wrong.
|
| That's actually a huge problem because it can veer onto
| intellectual dishonesty and being combative for nothing.
| Instead, one should be trying to look for the right/best
| path forward, regardless of what they thought. Should be
| easy to discard erroneous ideas.
|
| The goal is not to be right. It's to find what's right.
| goostavos wrote:
| >The goal is not to be right. It's to find what's right.
|
| This is why I think design docs need to be lightweight
| and reviewed early. Design docs shouldn't be a
| masterpiece perfected in isolation over the course of
| days or weeks. That guarantees the author has calcified
| their opinions. When I was on review panels at Amazon,
| 99% of them were an exercise in futility -- the author
| had already poured concrete. It is very, very, very hard
| to avoid the mental trap of "Hrmph! I've thought about
| this more deeply than anyone else" that comes from living
| down in the isolated world of "doing design."
|
| The earlier you get other eyes involved, the more likely
| people will actually listen to feedback and consider
| alternatives. You still, of course, need that heads down
| time to put in all the details, but the overall shape of
| the design shouldn't be a big reveal when you hit the
| design review.
| eschneider wrote:
| So much this. Bouncing early design ideas (informally)
| off other stakeholders or at least more experienced
| engineers can save SO much pain. The reverse of that is
| true, too: giving early feedback on other people's
| designs can give them the insights THEY need not to
| inflict pain on YOU.
| pfannkuchen wrote:
| I think there is a risk of going too far in the other
| direction leading to design by committee. It's often the
| case IME that a casual reader _actually_ hasn't thought
| through the problem enough to understand why their drive
| by feedback or alternative doesn't make sense. A process
| that results in those things getting accepted may just be
| introducing more entropy into the design process.
| aatd86 wrote:
| Good comment. I think both of your perspectives are fair
| and manifest in the size of what is being designed.
|
| Meaning that if someone designs something huge, end-to-
| end, it's going to be difficult for external people to
| address potential flaws within the design. A lot of
| interlinked parts requiring to have the full mental model
| loaded in the brain. So one should go step by step.
|
| It's also true that not every feedback is equal and it's
| important to think in advance about how to address
| rebuttals since most people don't give in-depth feedbacks
| but surface gut feeling (which can be invaluable too,
| even if simply in terms of UX), unless they have wondered
| about how to solve the same exact problem before. That
| requires more time spent thinking about the design.
| imissmymind wrote:
| I had a wise friend tell me that engineers are always in
| a state of being wrong. What you build today you will
| most likely laugh at in five years. The goal for today is
| to build the least wrong thing you can. I used to argue
| more than I should have simply because I didn't like
| being wrong either. After hearing this, it helped me to
| become more objective.
| burnished wrote:
| Then it'll be easy and fast and really not embarrassing at
| all.
| eschneider wrote:
| Hmm...most of the time when I do a design that's for
| something at all substantial, I'll usually go through a few
| ideas that seem reasonable at least through the "napkin
| stage" before dumping them in favor of what eventually
| becomes the "real design". I'd just save those napkins,
| list them in the alternatives section, and explain why they
| were abandoned. Easy.
| jppittma wrote:
| That's the idea. I try set it up so the time I spend on
| the idea in the doc is proportional to its viability.
| jvans wrote:
| the compensation structure in big tech makes people lose their
| minds optimizing for that next promotion/stock grant. It helps
| big tech retain talented people but the incentives to look
| "impactful" drive all the wrong behaviors
| pclmulqdq wrote:
| The mistake was production of a design doc instead of just
| writing the code. If it's trivial enough that there's nothing
| to discuss, you generally just change the code. If it's
| complicated enough, it becomes a negotiation process where at
| least 5 different people have to be able to put it into their
| perf if you want to get it done.
| weezin wrote:
| I'm dealing with this right now at another large company. Being
| asked to write a document for an integration we've done 20+
| times because its part of someone else's larger promo project's
| design.
| brotchie wrote:
| Used to feel this way on other teams. Almost as if you were
| expected to write them for the sake of writing them (cargo cult
| engineering).
|
| Now on a team of many OG Googlers (15+ years tenure) and Design
| Docs only exist when they're needed (something that touches
| multiple systems, something that's obviously complicated with
| many trade offs, etc) Otherwise it's just "write the CLS."
| andrekandre wrote:
| > Otherwise it's just "write the CLS.
|
| (apologies for the noob question) but what is cls in this
| instance?
| lupire wrote:
| Change Lists (Pull Requests, Change Sets)
| lupire wrote:
| One presumes in those simple CL cases, there is already a doc
| for the system being edited, and the new code followes the
| design.
| dataflow wrote:
| > Now on a team of many OG Googlers (15+ years tenure) and
| Design Docs only exist when they're needed
|
| This almost certainly has nothing to do with the team or
| tenure, but everything to do with what levels they are(n't)
| trying to get promoted to. Have you controlled for that and
| still seen a distinction?
| summerlight wrote:
| This is likely due to culture established by the teams working
| on old, mature products. There, you're going to work with at
| least 10 people to launch trivial projects. In my case, it's
| usually 20~30 people with a blast radius of 100~500. You're not
| going to casually 1:1 with all of them since you and they are
| all busy. If you don't get a good review from stakeholders,
| there's a good chance that some angry folks will come for you
| and make you roll back your launch.
|
| In these contexts, design docs are meant as an asynchronous
| communication tool for information heavy topics. And this is so
| asynchronous, you will talk to those people join 10 years later
| if you product becomes so successful. I've been saved multiple
| times thanks to some random design doc from 2010 that explains
| the weird decision that still haunts us. This probably doesn't
| work very well on lean/small teams or less complex tasks. But
| engineering culture usually has its own rationale and context,
| even if it has become a cargo culture.
| rexreed wrote:
| Another word for Design Doc = "Shelfware"
| iimblack wrote:
| Couldn't you just reference a recent doc and say this is mostly
| the same with these x differences leading to y alterations for
| z reasons?
| aprdm wrote:
| I interviewed a couple of folks from Google recently and it was
| mindblowing how they "work", it's very unfortunate. I feel for
| some of the people who only worked there their whole lives
| (e.g: from recent grad within the last 5y), it is unlikely that
| they actually know how to program.
| menzoic wrote:
| This isn't unique to Google. This is encouraged at Uber and
| Airbnb as well. I would think its a common practice. The idea
| is to show that you consider alternatives and did due
| diligence. Following the way its always been done isn't
| necessarily a good thing. If its a different product area there
| could be better approaches unique to that area. Its not fake
| work, it just proves you actually considered other approaches
| instead of blindly following status quo.
| ndjshe3838 wrote:
| 1. Creation and rapid iteration
|
| 2. Review (may be in multiple rounds)
|
| 3. Implementation and iteration
|
| 4. Maintenance and learning
|
| Missing step 5: Promotion and deprecation
| billfruit wrote:
| Can we see some real documents? It is as if software design
| process documents are the closest guarded secrets, because I have
| never seen a real document being available for case study.
| rullelito wrote:
| Companies keeping their IP a secret? Weird..
| faizshah wrote:
| Chromium: https://www.chromium.org/developers/design-documents/
|
| Kubernetes:
| https://github.com/kubernetes/enhancements/tree/master/keps
| iainmerrick wrote:
| Thanks for these links!
|
| I picked out one at random just to check if my skeptical
| reaction is fair: https://github.com/kubernetes/enhancements/
| tree/master/keps/...
|
| - OK, this is actually a really good and useful doc!
|
| - However, it's not an up-front design doc, it has clearly
| been written after the bulk of the work has been done, to
| explain and justify rolling out a big change. (See the
| "implementation history" timeline: https://github.com/kuberne
| tes/enhancements/tree/master/keps/...)
|
| - It looks like the template wasn't very useful; most of the
| required sections are marked "N/A", and there are comments
| like _The best test for work like this is, more or less, "did
| it work?"_
| jppittma wrote:
| Google is a huge company with ~180,000 employees. Sometimes
| people do sensible things.
| iainmerrick wrote:
| Well, sure! They have many thousands of really smart
| developers.
|
| I don't think this particular doc, although it is a
| really good doc, supports the design doc _process_ as
| described in the original article. It looks like good
| work being done in spite of the process, not because of
| it. It's obviously just one data point, but I'd put it
| down as a negative point.
|
| I wonder if anyone has done a proper investigation into
| whether the process is a good one?
| pjmorris wrote:
| > However, it's not an up-front design doc, it has clearly
| been written after the bulk of the work has been done, to
| explain and justify rolling out a big change.
|
| Shades of Parnas! [0]
|
| [0] 'A Rational Design Process: How and Why to Fake It',
| Parnas, Clements,
| https://users.ece.utexas.edu/~perry/education/SE-
| Intro/fakei...
| Nexialist wrote:
| The closest I have seen are the Oxide computer company RFD
| documents, many of which are public.
|
| Example: https://rfd.shared.oxide.computer/rfd/0177
|
| Main index: https://rfd.shared.oxide.computer
| swah wrote:
| I guess in the open source side we would talk about Github
| projects with the greatest READMEs...
| ajkjk wrote:
| Does it work? Is it better than alternatives? Where's that
| discussion?
|
| I worked at Amazon and their design doc culture was amazing. My
| next job was at a place that (I think) borrowed their engineering
| culture from Google (or maybe the ambient startup culture of SF?)
| and their design doc process was a pointless joke.
| r0ze-at-hn wrote:
| Which aspect of the Amazon design doc culture that you loved
| the most?
| blueboo wrote:
| Design docs are vehicles for discussion. The idea is that they
| are the most efficient way to communicate your intention,
| motivation, why not alternatives.
|
| They are one mechanism that fits in a broader working culture.
| If you're working solo, it's an extravagant exercise. If you're
| in a huge team, it'll enable leveraging more expertise across
| the team and act as documentation.
|
| There are a few different failure modes.
|
| * Valuing output not outcomes is classic misalignment. (writing
| 40 page docs for promo -- this doesn't work except for very
| junior folks who are proving the ability to string words
| together more than deep eng)
|
| * As mentioned, it's a bit much of solo teams. Other small
| teams can comfortably communicate through issues (Jira) plus
| breakout sessions to hash out ideas.
|
| * Engineers also need to be onboarded to effective design doc
| writing. (note a top commenter frustrated that their first
| effort isn't immediately met with adulation, a possible flag.)
|
| Writing about code is hard. Usually this is an exercise
| celebrated on HN. If you're in a team, beware if you find
| _your_ work is always that which doesn't need to be explained
| and deeply considered in a shareable doc.
| n3storm wrote:
| Was a "design doc" what get IMAP killed at Gmail then?
| staticfish wrote:
| I'm not fully understanding your comment. What do you think is
| happening or has happened to IMAP at Gmail?
| Macha wrote:
| Don't know what the parent poster thinks, but what is
| happening is this:
|
| https://workspaceupdates.googleblog.com/2023/09/winding-
| down...
|
| Which means that basically only apps that are approved by
| Google for OAuth can use IMAP in the near future.
| staticfish wrote:
| Interesting, thanks for the info. I must have missed this.
| It doesn't seem completely unfair to not pass your main
| Google password, and I imagine you still might be able to
| use generated application passwords if you really need the
| functionality (maybe).
| Macha wrote:
| The thing that is confusing here is you used to have to
| turn on less secure apps to use app passwords, and the
| article says that's getting removed for personal
| accounts. So while they don't say that they're removing
| IMAP via app passwords for personal accounts, there's a
| concern they might be effectively removing them it
| acatton wrote:
| I do not share the same experience as the author, as someone
| working for the mentioned company.
|
| There is a wide range of types of design docs, and none of them
| are useful. I've rarely seen any useful design doc at Google. I
| feel that design docs are for engineers who are too much process-
| oriented.
|
| Here are the types of design docs I've encountered in the wild:
|
| * The promo design doc: it's not really explaining what this is
| trying to solve, it's more stating that this project is awesome,
| and makes the company better. The logical conclusion is that the
| author of this doc should be promoted.
|
| * The turbo-encabulator[1] design doc: this is a technobabble
| design doc which is full of terms never encountered before, and
| which is not understandable unless you're a senior member of the
| team. I'm sometimes not even sure the senior members of the team
| understand it...
|
| * The new-grad design doc: this a design doc with no substance,
| but as the person just graduated from university, they felt
| compelled to make is as long as possible, to prove... I don't
| know what... It is not conveying any information. They most
| likely copied/pasted huge chunks of the code they've already
| written, to fill most of the ~70 pages of the doc.
|
| * The made-up-facts design doc: this a design doc full of
| "everybody knows that", "they all say". Of course, it's not as
| obviously done as some politicians do it. But the design doc will
| push their design with "this follows good practices", "this
| software is slow, therefore..." who defined the good practice?
| why is it a good practice? what is slow? was it measured? is it
| an end user feeling?
|
| This is 99% of the design docs I've seen out there. Of course,
| exceptions exists, but they're very rare, in my experience. I'm
| shocked that the author pushes for this practice... But again,
| they were no engineer, they were a director, I guess design docs
| make sense for their position, for which I'm still trying to
| figure out the value these folks bring.
|
| [1] https://en.wikipedia.org/wiki/Turbo_encabulator
| mike_hearn wrote:
| That must have changed. I worked there from 2006-2014, back
| then most design docs were useful and followed the basic
| structure described in the article (minus the system context
| diagram).
|
| I noticed early on though, that design docs maintained in
| Google Docs tended to be of lower quality than those maintained
| in the version control repository. Not sure if that was just a
| proxy for when they were written or whether the code review
| process is just more rigorous than editing things in Docs, but
| the only time I wrote a large (40 page-ish?) design doc I did
| it using hand written HTML and we worked through the code
| review system, as was traditional. I also posted it to the
| central mailing list and web server and got feedback from
| employee number 3, which was nice. The central location made it
| easy to find them as they were sorted by category.
|
| Still I don't recall design docs being important enough to
| matter for a promotion by themselves. Promos were supposed to
| be about overall impact, not production of specific artifacts.
| Of course the system was badly flawed, and often yielded
| surprising decisions in a bad way, but I don't remember ever
| reading an obviously-optimized-for-perf design doc back then.
|
| If you can find the website that holds the design docs hand
| written in HTML from the earlier years, try perusing some of
| those and see if you find them more useful (or would have done
| when the systems were contemporary). Some of them old ones like
| SmartASS were full of detailed explanations of the underlying
| equations and models, which was quite helpful for understanding
| how it worked, as well as the explanations of why those
| approaches were chosen. Reading those helped informed my own
| design work later. I wasn't a director, just an engineer, and
| they did help.
|
| There are also some Chrome design docs linked to from the
| chromium.org website that I found helpful in the past for
| understanding its design.
| ryandrake wrote:
| > Still I don't recall design docs being important enough to
| matter for a promotion by themselves. Promos were supposed to
| be about overall impact, not production of specific
| artifacts.
|
| How can you prove "impact" to a committee who otherwise
| doesn't know your work, without providing evidence in the
| form of docs, code examples, and other artifacts?
| mike_hearn wrote:
| Traffic, revenue.
| okdood64 wrote:
| That leaves out a lot of work that folks do that don't
| affect either of those directly.
| Cthulhu_ wrote:
| It sounds like there's no good review process for these; if
| they lack substance or are too long, they should never be
| published. But I take it that the people responsible for the
| people writing these also get the benefits?
| acatton wrote:
| There is a review process, but "yes, your comments are
| relevant, but they're just nit picking, can you just approve
| it so that we can start working on this project?"
| mewpmewp2 wrote:
| It feels like this case where when people are reviewing each
| other they might feel incentivised to be easy on each other
| in agreement so that both would get the promo easier,
| especially if they both think the doc is just for show to get
| the promo.
|
| Am I going to be a difficult person here finding each and
| single flaw about the doc or should I just allow it, let the
| other person get more visibility and just move on with my
| work. Why should I be a bottleneck here for a pointless
| battle.
| iainmerrick wrote:
| Yes! Although I think you forgot one, the "please just let me
| start coding" doc.
| jppittma wrote:
| My experience has been that the second one means, "I need to
| communicate with my team/TL what I'm doing/how I'm solving this
| problem." Eventually, when you go for promotion, you take
| documents in category 2, and add enough context to them that
| they become category one.
| apwell23 wrote:
| > There is a wide range of types of design docs, and none of
| them are useful.
|
| I write them mainly as a tool to get visibility with superiors.
| I try to make them as fancy as possible to to make them think i
| am "leadership material". I've been feeding them to chatgpt to
| rewrite them in fancy language.
| darkwater wrote:
| If you are a googler, you should be using Bard.
| apwell23 wrote:
| i am trying to get promoted not fired
| danielvaughn wrote:
| I've seen design docs work when you have a relatively high
| number of junior roles compared to seniors. It forces the
| junior developers to think through their solutions ahead of
| time and justify their decisions, and it also allows senior
| developers to validate those decisions and give feedback
| asynchronously.
|
| Granted, I've never worked in an org with more than 30-40
| engineers, as I've always worked in startups. I'm sure things
| are different in big tech, but I've had positive experiences
| with them.
| alwaysbeconsing wrote:
| Need time and effort to ensure junior docs are thorough.
| Usually multiple revision in my experience. This require
| acceptance from management that "just write code fast" is not
| a success path.
| klabb3 wrote:
| Spot on haha.
|
| The promo design doc is directly incentivized by managers: "if
| you just see a bunch of CLs, it doesn't tell a story. You need
| to write it down as a coherent narrative and get some >L5s to
| comment on it". "It's not for me it's for the committee - they
| aren't familiar with your work so you need to explain it".
|
| > But again, they were no engineer, they were a director, I
| guess design docs make sense for their position
|
| Yeah I think it's just high potency ammunition in the middle
| management[1] turf wars. Not even product managers care much
| about DDs.
|
| [1]: Liberal definition: anyone who uses the word "cross-
| functional" colloquially, independent of their actual job
| title.
| rockemsockem wrote:
| IMO the uses for a technical document (design doc or a shorter
| doc) is simple. If you get to the point where you can't hold
| every single detail about a project in your head at once then
| you should write a doc. Similarly, if it will take a long time
| (30 minutes at least) to explain to another engineer, you write
| a doc, to save yourself time.
|
| IDK how you can think that you never need to write a document
| alexchamberlain wrote:
| Red rag to a bull: "this is best practice". Really? There is no
| better way to do something given more context or experience? A
| better practice will never be discovered or devised?
| iainmerrick wrote:
| Documentation is good in general, but I think this approach is
| flawed:
|
| _These are relatively informal documents that the primary author
| or authors of a software system or application create before they
| embark on the coding project._
|
| "Before they embark on the coding project". The design _is_ the
| coding project, it 's all the same thing. The idea that you can
| work out the design on paper before committing any code is just
| wrong. (The design doc approach in fact admits that you need to
| write some code up front, but tries to strictly compartmentalise
| it as "prototypes that show the implementability of the design".)
|
| A big feature of the up-front design doc is that it gives people
| license to nitpick, AKA review, _before_ any serious coding
| starts. In my experience this usually means the doc gets extended
| by more and more caveats and discussions of pointless
| alternatives, and can become less of a "design doc" and more of
| a "please just let me start building this thing" doc.
|
| In cases where there are significant architectural problems that
| require a change in direction, they're better solved by _talking
| to and collaborating with the right people in advance,_ rather
| than crafting a detailed design doc only to have it shot down.
|
| If you stick closer to the "relatively informal document" idea,
| and _maintain the doc as you go_ , that can actually be useful,
| as it helps you produce useful documentation as well as a working
| system. But that's less "design doc" and more "write
| documentation as part of a continuous, collaborative process".
| rockemsockem wrote:
| If a project is sufficiently large and well thought out then
| architectural changes can be incorporated without too much
| extra work relative to the whole.
| trelane wrote:
| If
| rockemsockem wrote:
| No one is going to argue that poorly thought out design
| docs are a good thing. Like for docs to be useful they have
| to actually be good.
| trelane wrote:
| I meant more the overall system than the system changes
| in design doc itself. The new bits of the system one at
| least has a little control over.
| rockemsockem wrote:
| Ah, yes, there's less control there, lol.
| ChrisArchitect wrote:
| (2020)
|
| Some more discussion then:
|
| https://news.ycombinator.com/item?id=23915521
| glimshe wrote:
| If a big investor disguised himself and spent a few weeks as a
| Google engineer, they would quickly become an activist investor
| demanding Sundar's head. The magnitude of wasted human potential
| due to Google's design doc culture is almost incomprehensible.
| testfrequency wrote:
| I once completed a six month project that had a 9 page design
| doc, and the required director never signed off - but the work
| had to start.
|
| The project shipped on time (successfully), but the director gave
| feedback on the design doc and asked for changes to the approach
| a day afterwards.
|
| Awkwardly, that director had no clue the project shipped the day
| prior without his input, and he held a special meeting with me to
| apologize for completely ignoring months of requests to review
| and approve the design doc.
|
| I hate design docs. I wasn't even at Google, but worked somewhere
| that uses design doc culture. Thanks Google.
| lantry wrote:
| I don't see how design docs are the problem in your scenario
| testfrequency wrote:
| I don't disagree. What I didn't mention was that the project
| was delayed for weeks as I awaited sign off from the
| director.
|
| Getting a stale approval and request for revisions 6mo later
| after shipping only made me feel more so that design docs are
| just technical fluff pieces with no useful purpose beyond its
| origination.
| 3vidence wrote:
| Another Googler here.
|
| Lots of good comments already describing the uselessness of
| design docs at Google. I wanted to add one additional perspective
| that I find problematic.
|
| As mentioned design docs are "promo" material which causes
| massive amounts of fluff. But they also seem to substitute actual
| documentation!
|
| Every design doc is out of date pretty much the minute they are
| finished but teams point to them instead of writing
| documentation. The result.... documentation at Google as pretty
| bad and out of date.
|
| Honestly I would've really preferred if documentation /
| instructions were promo material instead of writing 20 pages
| about what you DIDNT DO. Write 2 pages about how to use what
| actually exists
| datahack wrote:
| A culture of design docs tends to push everyone into a
| justification layer for their work. Justification culture, even
| when it's peer reinforced as culture, is a fairly repressive
| pattern to innovators.
|
| This system tends to prevent visionary efforts and aspirational
| projects because non-consensus focused efforts are quashed and
| thinking "outside of the accepted norm" means you're going to be
| punished by the collective.
|
| This type of system breeds groupthink, and the tradition focused
| nature of "the way we do things" intrinsically enforces that
| doing anything else frequently becomes dangerous to your career.
|
| The valley has all manner of company cultures that rely on tropes
| wrapped in 'agile' and 'design thinking' verbiage that are
| primarily enshrined institutionalization masquerading as 'the
| right way' and usually comes with a healthy side dish of social
| enforcement of whatever 'engineering cult culture' variation that
| campus has arrived at.
|
| I can't tell you the number of people I've met who left Google
| because it was limiting their career, even when they were deeply
| comfortable working there. It's not a few.
| ilrwbwrkhv wrote:
| And that is why Google cannot build products at all. I just had
| a new pixel 7 fail on me yesterday. All of this pretend "we are
| very smart" behaviours are also a form of a bullshit job.
| Companies should focus and rate themselves on actual working
| products.
| cmrdporcupine wrote:
| Here's the thing though. Google builds the _actually_
| important products very well. Ads and Search. Particularly
| the former. The ad serving infrastructure at Google is huge
| and stable and makes insane money. Everything else is a
| sideshow.
|
| The real quality work being done at Google is by SREs -- not
| SWEs -- in Ads / Search & Core. The infrastructure they build
| and maintain is amazing and hard to explain to people
| outside. I say this as a former SWE there.
| cmrdporcupine wrote:
| _" I can't tell you the number of people I've met who left
| Google because it was limiting their career, even when they
| were deeply comfortable working there."_
|
| This is why they pay so high. It's a trap. That, and the
| apparent "status" of working there (which has mostly worn off
| now)
|
| You've expressed my frustration with what I experienced there
| exactly. But I do wish I could have that pay back...
|
| Also re: "agile" I came into "agile" 20ish years ago in the
| form of eXtreme Programming, and it looked nothing like the
| cargo cult that is SCRUM or its imitations today. It was, in
| the end, a set of precepts to put creative power into the hands
| of developers and let them just _get things done_ without
| management getting in the way of how -- _but_ in exchange the
| _customer_ is given the ability to say _what_ things get done
| and (to some degree) _when_. Developers do their own estimates.
| "You ain't gonna need it". No big "upfront design". Refactoring
| and testing, architecture and design _built in as a constant
| overhead_ as just standard best practices, not stories or tasks
| in themselves. Planning meetings are coworkers hashing things
| out in a room, and "stories" are sticky notes on a whiteboard
| expressed in minimal, non-technical terms. Standups are
| literally people in a circle giving a _very brief_ update, in
| case anybody else is interested, not a ritual to prove you 're
| attending work today, or to show off.
|
| In this system, design is an emergent property of a creative
| group of experts working together. It doesn't preclude design
| documents, and it _still_ involves architecture discussions.
| But it doesn 't _require_ an explicit PRD /design-doc process.
|
| How I'd like to work in a shop like that again. I can tell you
| Google was the polar opposite. Everything took forever.
| trelane wrote:
| > This is why they pay so high.
|
| Ah, ah, ah. This is why they pay so high _so far._
| cmrdporcupine wrote:
| Yes, I left just before (1 year) the bloodletting began.
| There was already a whiff that GSU refreshes weren't going
| to be as generous and perf was going to be tougher.
|
| I predicted the layoffs a year before started.
| yatz wrote:
| Spot on, especially in large teams with a diverse set of skills.
| alienchow wrote:
| The replies from Googlers in this thread surprise me. I've
| actually found DDs very useful for team onboarding, and for async
| stakeholder communications when making changes. Design docs
| typically also lead to fantastic g3doc documentation. It's a much
| better experience than having to fish around the team to piece
| together fragments of tribal knowledge about design choices for a
| system.
| methods21 wrote:
| How about some actual examples?
| larsrc wrote:
| Googler here. I used to hate writing design docs, even though I
| have several published papers. But a few years back I realized
| the main benefits for me:
|
| * It empties my head of the immediate parts of the idea, letting
| me move on to deeper parts and more productive considerations.
|
| * It makes flaws more obvious, especially to myself.
|
| * It makes it easier to share these thoughts, especially with
| people in other offices. They usually give really good feedback.
|
| * It gives me a much better idea of how much work is involved
| than if I just start coding.
|
| * It usually points out some things I need to learn before I
| start coding - adjacent systems, appropriate tech choices, etc.
|
| Yes, it's also good for promo, but a successful project is
| better.
|
| I often get comments on how useful my docs are, so I think I'm
| onto something.
| ZainRiz wrote:
| Same here. I found the biggest beneficiary of a design doc was
| my own thinking process (Xoogler here)
| larsrc wrote:
| Design docs are the _mise en place_ of software development.
| ein0p wrote:
| I feel like people would miss the forest for the trees here.
| Google design docs are nothing special. The special part is hard
| to replicate elsewhere: the reviews and the thoughtful comments
| they often receive that prevent a lot of wastage of time and
| resources, and the way these comments are selectively
| incorporated by the authors. That comes from knowing shit and
| giving a shit, the latter quality being in short supply as of
| late industry wide, including at Google.
| ZainRiz wrote:
| Google has the concept of a mini-design doc called a "One-pager"
|
| In 2018, the template for this "One-pager" was two pages long
| djmips wrote:
| "A clear indicator that a doc might not be necessary are design
| docs that are really implementation manuals."
|
| Where I work - this is what they want from a design doc. They
| want it to be such that you could hand it off to anyone and they
| could implement it.
|
| What does HN think about that?
___________________________________________________________________
(page generated 2024-05-07 23:01 UTC)