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

151–160 of 191 posts

Re: Design Docs at Google

#151

Post by maps7 »

nickbauman wrote: post #83
underdeserver wrote: post #65

Earlier quoted context omitted.

"The design is the code" does not follow from the idea that design and construction are not separate things in software. The thing to take away from that idea is that the design doc is not law written in stone, but a base for changes. It keeps your design honest on the high level. If you end up clashing with reality, and your design doesn't work out, you can backtrack to the design doc and refine it as necessary. In…

I think what you're talking about here is an "intention document" not a design document. Design is about planning. Which implies you define things in detail with steps and techniques. Intentions are about what you want to achieve. Very different.

A design is an outline, sketch, or plan. So it doesn't specify the level of detail.

Re: Design Docs at Google

#152

Post by joatmon-snoo »

dgb23 wrote: post #145
H8crilA wrote: post #135

Earlier quoted context omitted.

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.

Thank you for clarifying. My question is: when do I need a design doc, given I already have a maintained spec? Would they be used for as drafts or are they a complete separate thing?

I tend to reach for a design doc when I have (1) an ambiguous problem, (2) no obvious solution but N possible candidates, and (3) need feedback from multiple parties.

The primary functions (as people have mentioned elsewhere) are to (1) drive consensus and (2) record thought processes at the specific point in time.

Re: Design Docs at Google

#153

Post by whoevercares »

akhilcacharya wrote: post #139
whoevercares wrote: post #72

Earlier quoted context omitted.

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.

Sorry I mean compared to Google/FB... But that doesn’t translate to productivity though

Re: Design Docs at Google

#154

Post by gowld »

cameronbrown wrote: post #38
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…

I mean, you're right... but the goal of an analogy isn't to be perfect, but to be a rough mental model to quickly express a concept. I think it's fine. Different jobs require different levels of abstraction and design docs fulfil that role for software engineers.

An analogy is a blueprint for an explanation.

Re: Design Docs at Google

#155

Post by gowld »

maps7 wrote: post #150
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…

I work in an agile/scrum team. Do you have any experience in tracking the design doc work in this type of environment? It's hard to estimate how long a design doc would take since investigation into the solution and conversations with stakeholders could expand it.

If your estimates matter, you are doing agile wrong. Reserve some time, do some work, repeat.

Re: Design Docs at Google

#156

Post by lazyant »

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…

Yep. Add to the list: no Markdown support.

Re: Design Docs at Google

#157

Post by influx »

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…

I feel like Google has given up. The iOS Gmail app is terrible and buggy. The web app literally has a loading screen now. The GSuite set of products hasn't advanced much since it was acquired from outside Google. Google Cloud is getting curb stomped by Amazon and Microsoft. I guess they have Search still, but it's getting ad filled and tired. Not that I'm going to short GOOG anytime soon, but come on folks!

Re: Design Docs at Google

#158

Post by flarg »

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…

On the other hand I love the simplicity of Google Docs and we use it for everything at my (very large) employer and it's particularly suited to collaboration between technical people and business people. The familiar document interface works for the business folk whilst the ability to add and assign tasks as comments makes the whole experience seamless.

Re: Design Docs at Google

#159

Post by __float »

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…

Have you tried Dropbox Paper? Unlike what the name implies, it's the most non-print-focused editing experience I've used. Anecdotally, it's much more popular for design docs than Google Docs at my current employer.

Re: Design Docs at Google

#160

Post by akhilcacharya »

whoevercares wrote: post #153
akhilcacharya wrote: post #139

Earlier quoted context omitted.

> SDE1s with relatively low hiring bars as an SDE1...yikes dude.

Sorry I mean compared to Google/FB... But that doesn’t translate to productivity though

Again, that's a major yikes. I really don't think many others like me enjoy being called, er.., dumb.
Post reply on HN