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

81–90 of 191 posts

Re: Design Docs at Google

#81

Post by thebrokencube »

the_arun wrote: post #57

Do we have any templates for design docs created by Google, Facebook, Twitter etc.,? Not to be negative - My problem is there is no spec/standard template for design docs (like someone compared it with Blueprints). If we have a template approved by industry leaders - it will be convenient. Otherwise everyone creates them in their own way - convenient for their use cases. But this will miss the consistency and all nec…

I think if there was a rigid spec, it would work against one of the points made early on in this doc (which I think is worth taking note of):

> Rule #1 is: Write them in whatever form makes the most sense for the particular project.

This is an unsatisfying rule, but I think it's important because each team/problem space/etc. is different and too strict of rules can often lead to documents that may end up being shallow.

However this admittedly doesn't help with this other problem you brought up:

> Also, when design changes - these docs need to be updated.

... but that may be okay given a shared understanding of what the goal of said document is. If the goal is to gain consensus around an implementation (as opposed to it being a living document), the document may have served its purpose by the time that consensus is reached, even if later on the design changes. If the goal is to have living documentation of a system, then maybe the rough format specified in this article isn't correct.

One term I've heard for design documents is that they end up being a piece in a "Decision Log", which has helped me feel less bad if the document falls out of date. These documents end up being more point-in-time representations of the collective understanding/opinions of how a specific project/system was being thought of, and that has its own advantages even if it falls out of sync.

Re: Design Docs at Google

#82

Post by etse »

whoevercares wrote: post #75
everlost wrote: post #64

Earlier quoted context omitted.

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?

The review process has a human factor in it IMO. I’ve seen many designs get scratched just because “this should be done and designed by Team B rather than you”. Problem is that could come late. Sometimes it could be a career development bummer for the engineers who invest a lot into the design.

But isn’t that better than code (especially if working) that gets scratched? I think designs that are scratched indicate you don’t understand the value you contribute to your company (or that management sees in you) which should be the root concern for the career development.

Re: Design Docs at Google

#83

Post by nickbauman »

underdeserver wrote: post #65
nickbauman wrote: post #43

Earlier quoted context omitted.

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

Re: Design Docs at Google

#84

Post by theptip »

Areibman wrote: post #31

>Finally, the overhead of creating and reviewing a design doc may not be compatible with prototyping and rapid iteration. However, most software projects do have a set of actually known problems. Subscribing to agile methodologies is not an excuse for not taking the time to get solutions to actually known problems right. Here lies the biggest problem with the article. Most software projects _do not_ have a set of act…

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 that covers the whole project, rather than just designing what you're going to work on next. I can wholeheartedly agree with that objection.

However everything in the article is consistent with epic-level or story-level design. As the complexity and cost of change increase, more up-front design is appropriate. None of that is incompatible with the agile tenets of building small increments and delivering them often to make sure that they add value.

If you're lucky enough to be working in the early stages of a project with a few thousand lines of code, and little to no production data on which to maintain integrity, then the value of formal design docs goes way down. But it's important to know that you'll need them later.

Re: Design Docs at Google

#85

Post by packetslave »

the_arun wrote: post #57

Do we have any templates for design docs created by Google, Facebook, Twitter etc.,? Not to be negative - My problem is there is no spec/standard template for design docs (like someone compared it with Blueprints). If we have a template approved by industry leaders - it will be convenient. Otherwise everyone creates them in their own way - convenient for their use cases. But this will miss the consistency and all nec…

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.

Re: Design Docs at Google

#86

Post by draw_down »

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…

What engineers actually do is determined by the incentive structure they work in. If shipping is prioritized all the time above everything else, one of the things that will suffer is documentation.

If people get promoted in spite of not doing a good job of documentation, now you know why it doesn't happen.

Re: Design Docs at Google

#87

Post by whoevercares »

etse wrote: post #82
whoevercares wrote: post #75

Earlier quoted context omitted.

The review process has a human factor in it IMO. I’ve seen many designs get scratched just because “this should be done and designed by Team B rather than you”. Problem is that could come late. Sometimes it could be a career development bummer for the engineers who invest a lot into the design.

But isn’t that better than code (especially if working) that gets scratched? I think designs that are scratched indicate you don’t understand the value you contribute to your company (or that management sees in you) which should be the root concern for the career development.

Yea, designs are cheaper then actual implementation. It’s not always the case that the engineer doesn’t understand the value but most times it’s about the management/PM can’t get things finalized over a long period of time. Sometimes I feel it’s just politics in some cases. Don’t you ever need to fight to do some high visibility work?

Re: Design Docs at Google

#88

Post by Ozzie_osman »

Honestly I sometimes write a design doc even if no one else will read it. It can be as short as a few sentences, if needed.

The main benefit is it forces you to:

1. Think strategically, not tactically, about what you're about to build. Beyond just "I need to get this working now".

2. It makes sure you can describe what you're about to do in plain English (or plain English plus some diagrams). If you're struggling to do that it's probably a sign you need to rethink your approach.

Obviously, the organizational benefits described in the link are really important, too, but if all you've done is just 1 and 2 above that's already worth your effort.

Re: Design Docs at Google

#90

Post by thehappypm »

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…

In a much more real sense, the code itself is the blueprint. The compilers/interpreters lay the bricks and mortar for us.
Post reply on HN