Design Docs at Google • Hacker News Board

Re: Design Docs at Google

#131

Post by maxwellg » Wed, Jul 22, 2020, 8:22 PM UTC

staplung wrote: post #130

I worked at Google for 4 years. One thing that has always surprised me about documentation at Google is that they use Google Docs (just like everyone else) but have never seemed interested in making it less of a terrible tool for the task. It's relentlessly print oriented, which makes almost no sense these days (when was the last time you printed out a Google doc?), has no affordances for dealing with pre-formatted t…

Comment discovery is also horribly broken. So often, conversations _about_ a document contain information that don't necessarily _belong in_ the document, but still have value for future readers. Resolving comments makes it much harder to find them.

Re: Design Docs at Google

#132

Post by xnx » Wed, Jul 22, 2020, 8:26 PM UTC

staplung wrote: post #130

I worked at Google for 4 years. One thing that has always surprised me about documentation at Google is that they use Google Docs (just like everyone else) but have never seemed interested in making it less of a terrible tool for the task. It's relentlessly print oriented, which makes almost no sense these days (when was the last time you printed out a Google doc?), has no affordances for dealing with pre-formatted t…

Exactly correct about the print-oriented interface. Writely, and earlier versions of Google Docs didn't force you to pretend you were writing on a piece of paper. I would love a "Google Docs for text files"!

Re: Design Docs at Google

#133

Post by rckoepke » Wed, Jul 22, 2020, 8:33 PM UTC

I'd love some examples of real-world design docs.

Re: Design Docs at Google

#134

Post by packetslave » Wed, Jul 22, 2020, 8:40 PM UTC

cameronbrown wrote: post #100

packetslave wrote: post #85

Earlier quoted context omitted.

The canonical Google design doc template is called the Bluedoc. An example is here: https://docs.google.com/document/d/18hYAQCTsDgaFUo-VJGhT0Uqy... Delete everything but the headers and you have a bluedoc.

There are also a few domain-specific headers in-use: Privacy, Ethics and Security are very common to see.

yeah, Monitoring and Logging are also common to see.

Re: Design Docs at Google

#135

Post by H8crilA » Wed, Jul 22, 2020, 8:43 PM UTC

dgb23 wrote: post #51

Related: https://www.joelonsoftware.com/2000/10/02/painless-functiona... My opinion: If you don't specify things in a separate document in the form of text and pictures, then you end up doing it anyway but ad-hoc. Your "non-spec" now leaks into multiple tools and channels that likely don't talk to one another: emails, instant messages, file storage, notes, phone calls & discussions (AKA in your head/memory), Trello/A…

A design doc is not exactly a spec. It is a medium for discussion and a snapshot of what people thought at the time. They do get old pretty quickly and there's no expectation that anyone will update them (always put dates on such documents!).

I think that specs should be checked into the codebase, either through some kind of code annotation, or next to it in text files, depending on what is it that you're doing.

Re: Design Docs at Google

#136

Post by akhilcacharya » Wed, Jul 22, 2020, 8:47 PM UTC

staplung wrote: post #130

I worked at Google for 4 years. One thing that has always surprised me about documentation at Google is that they use Google Docs (just like everyone else) but have never seemed interested in making it less of a terrible tool for the task. It's relentlessly print oriented, which makes almost no sense these days (when was the last time you printed out a Google doc?), has no affordances for dealing with pre-formatted t…

At my company we use the internal Wikis or Quip for this. Versioned and effectively markdown formatted with builtin live charts or spreadsheets, respectively.

Re: Design Docs at Google

#137

Post by solidasparagus » Wed, Jul 22, 2020, 8:50 PM UTC

everlost wrote: post #64

cameronbrown wrote: post #4

Design docs are one of my favourite things about software engineering. If code is the bricks and mortar, then these docs are the blueprints. I know this is fairly controversial, but our jobs isn't just to write code. Navigating organisations and achieving consensus between a lot of teams/technologies is a huge part of it. Design docs are a way to get all of that out of the way _before_ writing thousands of lines of c…

My experience has been that writing the design doc is not as controversial, as much as the review process. Does anyone have any insights on how to make the reviews more constructive + quicker?

Some things I've found useful.

- Have a single person (engineer) who is responsible for making final decisions. Gather input from others but there should be one individual who is responsible for making sure that the design has a consistent vision that meets the goal. If a non-critical decision is taking too long, just make a choice and run with it.

- Be clear about the goal of the project. At Amazon they use the PRFAQ process where you need to begin by writing a costumer-centric press release that basically details why customers should be excited about the project. This helps keep design discussions focused on the customer.

- Be clear about the non-goals or things you will not do.

- At the beginning of a review meeting, have everyone read the document. The document should describe all relevant context. At the end of reading the doc, everyone should have enough context to understand and discuss the design - everyone should have the same understanding of the design (i.e. no confusion about which version of the doc we're talking about, no one who didn't have enough time to read the doc beforehand and just skimmed it).

- Have people add comments as they read through it, the authors can respond to the comments in real-time and once everyone is done reading the doc, the comments act as a list of things that need to be discussed.

- Have the doc be the absolute source of truth. If it's not in the doc, we're not planning on doing it. This prevents cases where you have a chat with someone about an idea, look into it further and decide to not do it/do it differently, but the reviewer thinks you are still going to do it, but you just haven't updated the document yet.

Re: Design Docs at Google

#138

Post by kcudrevelc » Wed, Jul 22, 2020, 8:51 PM UTC

I've worked at Google for a while, and a few years ago I wanted to release an open-source project. Since the code was going on Git, it made sense to throw the design there too, so I just added a DESIGN.md to the top-level of the project. This has had a remarkably nice effect: sometimes, when people make large changes to the project, they update the design to reflect the changes!

See this lovely commit as an example: https://github.com/google/stenographer/commit/d678531a3e5a87...

Re: Design Docs at Google

#139

Post by akhilcacharya » Wed, Jul 22, 2020, 9:00 PM UTC

whoevercares wrote: post #72

koheripbal wrote: post #66

Earlier quoted context omitted.

Does duration really measure depth of design?

Yeah some are churns from reviewers, partner teams or even politics. The depth of the design are commonly pretty deep to the ground, because Amazon has many SDE1s with relatively low hiring bars and the design need to be super detailed for a safe execution

> SDE1s with relatively low hiring bars

as an SDE1...yikes dude.

Re: Design Docs at Google

#140

Post by learc83 » Wed, Jul 22, 2020, 9:06 PM UTC

fsociety wrote: post #129

sarchertech wrote: post #35

Earlier quoted context omitted.

>If code is the bricks and mortar, then these docs are the blueprints. That analogy falls apart quickly. Design docs aren’t specific enough to be analogous to blueprints. You can give a set of blueprints to 3 different construction firms and get fundamentally the same building. Try giving design docs to 3 different development shops and see what happens. The problem is that the only way to get to that level of specif…

The analogy actually makes sense if you’ve worked manufacturing things from blueprints. If you hand one complex blueprints to three random construction firms, from a distance you’d get the same result, nearly, but up close a lot would’ve changed during the project. There is a reason why engineers are required to inspect the project at some interval and perform quality checks.

At some level sure there will be differences, but for the end users, unless something went wrong, they won't be able to tell much of a difference.

Blueprints for a house are much, much closer to being reproducible than design docs for a software project.

If you give design docs to 3 separate dev shops, the end results will be wildly different.

>There is a reason why engineers are required to inspect the project at some interval and perform quality checks.

It's true that there is still some room for interpretation because blueprints are still a model. But most of what your talking about is because people will cut corners and not follow the specifications, not because the specifications aren't there.