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

41–50 of 191 posts

Re: Design Docs at Google

#41

Post by ChrisMarshallNY »

shadowgovt wrote: post #37
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…

> basically requires that everyone involved be extremely experienced, and kept together as a team for years Yep, that's the issue. Businesses can't codify that approach into a process because they can't make any guarantees around that. Your approach is "conclave of wizards." It's a high-output approach that is the right thing for some problem domains, but (a) it isn't repeatable and (b) it isn't sustainable (if a cri…

> Give up and shut down?

In some cases, yes. That's exactly what needs to happen.

If the business model is dependent upon the "conclave of wizards," then they are a critical path resource, just like a major supplier or business partner, which, if withdrawn, could doom the company just as certainly.

If the corporation refuses to treat that resource as a valuable, critical resource, then they don't deserve to stay in business.

Managing that type of team is not something that is really taught in school. It comes from experience, and also requires a level of empathy that is, quite honestly, almost nonexistent in today's business culture.

Re: Design Docs at Google

#42

Post by dilyevsky »

jhallenworld wrote: post #36

Design docs should be written in Markdown and stored in git. The advantage here is that the git hash can be used as a legal reference, for example in the case where a contractor is expected to implement the design.

I’ve tried this and I tried just gdocs like everyone at google did. Gdocs seems better for iterating because github review ui sucks (and everyone else sucks even more). If google critique was publicly available I’d much prefer markdown for designs

Re: Design Docs at Google

#43

Post by nickbauman »

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…

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.

Re: Design Docs at Google

#44

Post by nkingsy »

The emphasis on trade offs is the most important part for me, because it formalizes the search for alternative approaches. In the majority of my design docs, I end up swapping an “alternative” into the doc itself as I find myself more convinced by the alternative solution.

Re: Design Docs at Google

#45

Post by sethammons »

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…

At work, we call them blueprints :). A fantastic way to get early feedback before writing any code, especially important for junior teams who may forget to think about failure cases and operability.

Re: Design Docs at Google

#46

Post by sgt-serverless »

sarchertech wrote: post #39
cameronbrown wrote: post #38

Earlier quoted context omitted.

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.

Yes models can be helpful even if they aren’t perfect. But not only is this one too far off to be useful, it does more harm than good. The expectations that happen when people (specifically managers) start thinking of design docs as blueprints, software architects as architects, and developers as builders are downright dangerous.

Dangerous seems a bit extreme. If developers aren't builders, then what are they?

Re: Design Docs at Google

#47

Post by bdefore »

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…

While I agree, I find this common argument to have a faulty rhetorical approach. Leadership can often be allergic to allegations that there are problems that they don't know about. They can be outright defensive towards suspicions of uncertainty.

I feel there may be a better way to express the utility of rapid iteration and design-as-you-go without triggering a fight response.

Re: Design Docs at Google

#48

Post by shadowgovt »

ChrisMarshallNY wrote: post #41
shadowgovt wrote: post #37

Earlier quoted context omitted.

> basically requires that everyone involved be extremely experienced, and kept together as a team for years Yep, that's the issue. Businesses can't codify that approach into a process because they can't make any guarantees around that. Your approach is "conclave of wizards." It's a high-output approach that is the right thing for some problem domains, but (a) it isn't repeatable and (b) it isn't sustainable (if a cri…

> Give up and shut down? In some cases, yes. That's exactly what needs to happen. If the business model is dependent upon the "conclave of wizards," then they are a critical path resource, just like a major supplier or business partner, which, if withdrawn, could doom the company just as certainly. If the corporation refuses to treat that resource as a valuable, critical resource, then they don't deserve to stay in b…

Indeed. So the correct thing for a business to do for both its short- and long-term survival (since we can't know a-priori whether the conclave of wizards will be stable) is to minimize the odds of forming one in the first place.

Businesses are structures that minimize risk. A core set of specialists who can't be replaced without tanking the business's performance is a risk. And a hard-to-quantify one at that.

Unless, of course, the business is not setting out to minimize risk, but instead to shield some less-risky structure from outsized risk exposure. Like, say, a startup company funded by angel investors trying out experimental technologies in the hopes of hitting on a jackpot new system that a big corp could then buy. If they fail, only the angel investor money is gone. If they succeed, a risk-averse business can buy a valuable asset.

But the first thing that business will want to do to maintain its long-term risk profile is fire the wizards. ;)

Re: Design Docs at Google

#49

Post by pmb »

dilyevsky wrote: post #42
jhallenworld wrote: post #36

Design docs should be written in Markdown and stored in git. The advantage here is that the git hash can be used as a legal reference, for example in the case where a contractor is expected to implement the design.

I’ve tried this and I tried just gdocs like everyone at google did. Gdocs seems better for iterating because github review ui sucks (and everyone else sucks even more). If google critique was publicly available I’d much prefer markdown for designs

The best is to get agreement on the design is gdocs and then export it to Github so that the design and code live next to each other.

Re: Design Docs at Google

#50

Post by lowiqengineer »

I wonder why the "at Google" is necessary for the title. I'd be very surprised to see an organization not use some sort of design doc before building things - the only thing that would be different is the scale and scope of them.

Of course, you won't see a "Design Docs at Amazon" on the front page of HN for...some reason. Gee, I wonder why?

Post reply on HN