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

171–180 of 191 posts

Re: Design Docs at Google

#171

Post by noir_lord »

sfifs wrote: post #164
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 workplace, we've started using Confluence for some projects and it's been incredibly productive. I still loathe JIRA but Confluence has been incredibly good for technical collaboration and documentation.

My experience as well - We are all in on Atlassian.

Confluence is brillient, bitbucket is meh but OK and JIRA is an utter tire fire both in how it's built and what it does but PHB's and PHB-shaped objects love it.

Re: Design Docs at Google

#172

Post by ciconia »

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 think the target audience is mostly non-programmers AKA normal people. It's a general-purpose tool hence the feature set.

Re: Design Docs at Google

#173

Post by LdSGSgvupDV »

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…

How did you balance the coding and documenting for totally new product when there are rapid iterations?

Re: Design Docs at Google

#174

Post by m463 »

m0zg wrote: post #165
influx wrote: post #157

Earlier quoted context omitted.

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!

One thing people don't get about Google is how it motivates its employees. You get promoted for _taking credit_ for _launching new stuff_. I deliberately mention "taking credit", because if you can't take credit for the work you've done, you're better off not doing anything at all; a prime example of this is launching a project someone else started but abandoned. Note that you also don't need to do much work to be ab…

That seems to agree with what a friend of mine who worked there, and how he was rewarded (or not).

I can't help but think they are rewarding the right thing -- new shiny things may have the best ability to bring stragglers onto google the platform.

Unfortunately, it leads to the feeling that google just dabbles in things.

Re: Design Docs at Google

#175

Post by maps7 »

gowld wrote: post #155
maps7 wrote: post #150

Earlier quoted context omitted.

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.

But you have to estimate to know how much work you'll fit into a sprint, right? Nothing happens if the estimate is wrong really but it helps fit an amount of work into a period of time

Re: Design Docs at Google

#176

Post by pradn »

m0zg wrote: post #165
influx wrote: post #157

Earlier quoted context omitted.

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!

One thing people don't get about Google is how it motivates its employees. You get promoted for _taking credit_ for _launching new stuff_. I deliberately mention "taking credit", because if you can't take credit for the work you've done, you're better off not doing anything at all; a prime example of this is launching a project someone else started but abandoned. Note that you also don't need to do much work to be ab…

That's a popular perception but it's not totally true. You need to be able to measure improvements you make, which might make a large category of possible improvements untenable from a perf point of view. But if you can show satisfaction scores or latency numbers or action-conpletion metrics or even just customer comments saying it solved their issue, that's plenty reason to attempt the change. The system encourages you not to work on things that "feel good" but instead things that are measurable. There's pros and cons to this as you can imagine.

That all said, I think the bigger problem is a willingness to put out things that don't meet a high standard. Ex: the new web GMail launched while slower than the older one. This was done to get new features out to users faster, but it doesn't feel that great from a product excellence POV. There's no Steve Jobs figure telling us the Pixel 4 doesn't look great and as a consequence we should go back to the drawing board. It's more like there's a set of market survey results and the phone was made to check those boxes.

Re: Design Docs at Google

#177

Post by amf12 »

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…

> One thing that has always surprised me about documentation at Google is that they use Google Docs

When did you work at Google? There are markdown supported wiki tools now for internal documentation. It supports pre-formatted code, graphs, etc.

Re: Design Docs at Google

#178

Post by s3r3nity »

m0zg wrote: post #165
influx wrote: post #157

Earlier quoted context omitted.

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!

One thing people don't get about Google is how it motivates its employees. You get promoted for _taking credit_ for _launching new stuff_. I deliberately mention "taking credit", because if you can't take credit for the work you've done, you're better off not doing anything at all; a prime example of this is launching a project someone else started but abandoned. Note that you also don't need to do much work to be ab…

> Having said that, I still prefer GSuite to Office. Microsoft has set the bar very low indeed.

Depends upon which pieces. You can pry Excel from my cold, dead hands; OneNote is still an amazing piece of software that is getting pretty sweet updates; Outlook by itself is pretty solid for 80% of use cases, with fast iOS/Android apps; everything can be tweaked to your liking with some VBA scripting.

Onedrive also gives you more free space vs. Google Drive when signing up, I believe, though creating Google Docs / Sheets / Slides don't contribute to GDrive storage space - which was the deciding factor for us.

Re: Design Docs at Google

#179

Post by Kinrany »

sarchertech wrote: post #113
Kinrany wrote: post #80

Earlier quoted context omitted.

It's true that they're not reproducible. Are there other noticeable differences?

Reproducibility is just a side effect of lack of specificity, which is the major difference and the entire point of my critique. Design docs don't tell you enough to actually build the thing you want to build.

I mean, are there any practical consequences other than the inability to make the same thing twice?

Re: Design Docs at Google

#180

Post by underdeserver »

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.

The design doc is definitely the plan. But if the plan doesn't work when faced with reality, you need to change the plan, and therefore also the design doc.
Post reply on HN