Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Design Docs at Google

industrialempathy.com

Post reply on HN
Print view View original

121–130 of 191 posts

Re: Design Docs at Google

#121

Post by theptip »

nawitus wrote: post #112
theptip wrote: post #84

Earlier quoted context omitted.

I don't agree with this viewpoint. Agile is about just-in-time design, not no-design. At some point, you need to decide what the next increment you're going to build is. Before you write the code for that increment, you have by definition picked an actually known problem to solve, and for that you should write a design doc. I think what you're objecting to is the waterfall concept that you would write a design doc th…

Are you suggesting to write a design doc every sprint, e.g. two weeks?

In some sprints my team will write multiple design docs, though that's uncommon. For example, if we're building two new features, and each is self-contained. Those design docs are probably small.

In other sprints, we won't author any new docs, for example if we're implementing and shipping/demo'ing chunks of a large, complex feature for which we've already completed the technical design.

I'd suggest coupling design docs to stories/epics, not sprints.

Re: Design Docs at Google

#122

Post by ChrisMarshallNY »

smichel17 wrote: post #110
ChrisMarshallNY wrote: post #16

I'm of a mind to reduce documentation as much as possible, or keep it as vague as possible. That's because I came from an environment that insisted on incredibly detailed, formal, approved-by-everyone-including-the-mens-room-attendant, documents. These became "concrete galoshes"[0] that turned what should have been an agile, iterative project into a waterfall behemoth that cost a mint, took forever to make, and deliv…

Meta: Why do you link to medium when the articles are also posted on your website, which I assume is the canonical version if there were a discrepancy? Also, I reviewed your privacy policy and while I am not a lawyer, I believe your cookie popup is not unnecessary. As far as I understand GDPR, it is not necessary to ask for consent separately if the cookies you're setting are strictly used to fulfil an explicit reque…

Thanks! That tip about the popup is good. I'll remove it.

I would be happy to link to my regular site, but I assume that people prefer Medium; I guess because of the standardized layout (which I don't love), and the ability to use apps and semantic API hooks.

There are a few series on my site that are not available on Medium [0][1][2][3][4][5]

[0] https://littlegreenviper.com/series/swiftwater/ (I republished one of these on Medium).

[1] https://littlegreenviper.com/series/spm/

[2] https://littlegreenviper.com/series/bluetooth/ (Which was actually #1 on HN for a little while -St. Paddy's Day)

[3] https://littlegreenviper.com/series/bluetooth-2/

[4] https://littlegreenviper.com/series/streaming/

[5] https://littlegreenviper.com/series/stylist/ (Which is a decade old)

Re: Design Docs at Google

#123

Post by jeffbee »

cmrdporcupine wrote: post #117
jeffbee wrote: post #107

Earlier quoted context omitted.

That is not a design doc, that is a format specification. It jumps directly to the implementation details without discussing the motivation. The reader has no way to evaluate the utility of the example JSON because the doc has not stated any use cases.

And frankly that's how most of the design docs at Google really are. They're post-facto descriptions put together for the purpose of gaining promotion.

Yes and the way you can tell is the doc title is "FooBar Design Doc" but the shortlink is "foobarforperf".

Re: Design Docs at Google

#124

Post by javier10e6 »

sarchertech wrote: post #35
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…

>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…

I agree wholeheartedly. The best software documentation is the an actually well written software module + test that explains its functionality.

Re: Design Docs at Google

#125

Post by javier10e6 »

nickbauman wrote: post #43
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…

This is something that should be taught to folks while they're still in school. The "blueprint analogy" has baked in the idea that there's a "design phase" and a "construction phase" and that these are often discreet parties. Nothing could be more incorrect when it comes to software. In software, the design is the code. The compiler/interpreter are the construction of the system.

The Code is the Design and the design uncovers good or bad written code. GoF design patterns were modeled after well written code. Anti-patterns (the swiss army knife is my favorite) are bad written code.

Re: Design Docs at Google

#126

Post by jbeda »

jeffbee wrote: post #74

A fun activity if you’re a Googler is to go read ancient design docs, like the original pitch for bigtable. They are pretty short for the most part, and they were written by the legends. These are the Federalist Papers of your company, they give real context to how the company arrived here. In particular I always enjoyed reading the jarring parts were they describe something that definitely did not make it into the i…

I wrote a design doc/PRD for k8s that outlined the basic API, distributed structure and why/how it related to open source and the marketplace. I lost it when I left google. It was a google doc IIRC and wasn't checked into source control.

Re: Design Docs at Google

#127

Post by bo1024 »

ChrisMarshallNY wrote: post #16

I'm of a mind to reduce documentation as much as possible, or keep it as vague as possible. That's because I came from an environment that insisted on incredibly detailed, formal, approved-by-everyone-including-the-mens-room-attendant, documents. These became "concrete galoshes"[0] that turned what should have been an agile, iterative project into a waterfall behemoth that cost a mint, took forever to make, and deliv…

That environment reminds me of Conway's law[1] - code structure reflects organizational structure.

It sounds like the problem was decisionmaking power was spread out among far too many people. Detailed documentation was a side effect. Removing the documentation likely wouldn't have fixed the problem.

[1] https://en.wikipedia.org/wiki/Conway%27s_law

Re: Design Docs at Google

#128

Post by choppaface »

It would be great to see some actual design docs in a blog post versus a summary article with zero primary references. (A postmortem of some design docs would be incredible!).

One of the hardest things about introducing a design doc process to a team of engineers is providing concrete examples as seeds and ensuring feedback to make the process actually work. It can be really jarring to introduce the design doc philosophy to a larger team if all they've been doing is Scrum every week. Moreover, typically design docs happen at a quarterly rhythm and feedback periods can take weeks-- this slow cycle is a major impediment to consensus and learning.

All this calls for material that speaks to differentiated learning. Extolling "we do this at Google" is a leaf in the wind.

Re: Design Docs at Google

#129

Post by fsociety »

sarchertech wrote: post #35
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…

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

Re: Design Docs at Google

#130

Post by staplung »

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 text (e.g. code), has basically no support for mathematical formulas, etc. In fact its actually evolved to be less suited to the task of technical documentation since it began given that earlier versions at least allowed you to define your own paragraph styles. I was hoping that Google Colab might evolve into a better/more general tool for writing tech specs but it doesn't seem to be moving in that direction really.
Post reply on HN