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

101–110 of 191 posts

Re: Design Docs at Google

#101

Post by jkaptur »

It's important draw a distinction between a "design doc" and "documentation". tl;dr: "ought" vs "is".

A "design doc", as described in the article, is a tool to help make a decision. It's a proposal. It is "ought". It describes the state of the world at a point in time, the desired change, and how to make it. Once the decision is made and the work is begun, it's rarely updated.

"Documentation" is just the state of the world (generally "now" or "at release x.y"). It describes the design and use of the system, but has very little digression into ways it could be different. If it links to a design doc, it should be for

Once you draw this distinction, it's clear that design docs should be in something like Google Docs, while documentation should be in something like a wiki or git. It's clear why it's fine for a design doc to be out of date, but it's a big problem if documentation is. etc.

Re: Design Docs at Google

#103

Post by taeric »

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…

This often betrays an understanding of blueprints to builds that just isn't true. The blueprint of simple things is how they are built. Even complicated things, this will be roughly true for new things.

For old things and complicated things, though, they were how things could be attempted to be built. And with the builder being someone else, there had to be an audit from the build to the blueprint, if you really want confidence in that statement.

Re: Design Docs at Google

#105

Post by gregdoesit »

“Unstructured text, like in the form of a design doc, may be the better tool for solving problems early in a project lifecycle, as it may be more concise and easier to comprehend, and communicates the problems and solutions at a higher level than code.“

I could not agree more. I came across the concept of design docs consistently used for all projects at Uber. They were called RFCs here and they were introduced very early on. I wrote in more detail about my experience using these and how I am pretty sure they helped scale the engineering culture [1]. The most surprising thing I’ve observed is how sending these design docs out to all of engineering worked really well, until the org was over a thousand engineers.

[1] https://blog.pragmaticengineer.com/scaling-engineering-teams...

Re: Design Docs at Google

#106

Post by wsetchell »

The article does not point out how the system can go astray.

Design docs are great when they can in 1-2 pages describe a how an important/large/complex system will work and the tradeoffs made when designing it.

Some groups in Google confuse design docs conflated with the promotion process, and thus engineers start create long/time consuming docs for every little thing as part of building a case for promotion.

Re: Design Docs at Google

#107

Post by jeffbee »

jp42 wrote: post #102

After reading this article I can relate it event trace (Chrome tracing) design doc form google, very succinct to the point: https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQt... !

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.

Re: Design Docs at Google

#108

Post by blargmaster33 »

Properly done MIL-STD-498 is a joy to behold.

Operational Concept Description (OCD) - Used to sync with the marketing/sales non technical people.

System/Subsystem Specification (SSS) - Software/System architect and agile team leads sync here

System/Subsystem Design Description (SSDD) - Developers documents a rough outline of how stuff was done.

Re: Design Docs at Google

#109

Post by brown9-2 »

thebrokencube wrote: post #81
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 shallo…

The first points here are absolutely correct. These documents are a way to communicate and get feedback (and iterate) on an idea with a group of people in your organization. Different organizations will communicate differently, and have different needs.

Re: Design Docs at Google

#110

Post by smichel17 »

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 request. Eg, if a user checks "stay logged in", you don't need to ask separately to set a "wordpress_logged_in_xxxxx" cookie; the user already gave their consent by checking the box. Same with a session cookie when they log in, or a cookie for persisting settings. Not to mention, I there's no prominent log in link, so I'm guessing you are the only one who does that, in which case you'll never be setting cookies on other people's computers anyway :)

These things still need to be described in your privacy policy, but you don't need to bother users with them; you only need the consent box when you're using cookies for something the user doesn't explicitly request, like tracking (regardless of whether it's a discrete tracking cookie or you're using their login cookie to do it). I didn't see any of these things in your website privacy policy.

Not needing to bother your readers with consent popups is a great advantage that the GDPR gives privacy-respecting websites like yours!

Post reply on HN