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

31–40 of 191 posts

Re: Design Docs at Google

#31

Post by Areibman »

>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 actually known problems. Agile exists precisely because it's hard to pin down what problems are, and you learn much more about your product with gradual experiments than with some grand, centralized design.

Unless you are totally certain about your solution, design documents don't have a place for most projects.

Re: Design Docs at Google

#33

Post by colonelxc »

commandlinefan wrote: post #17

I like the idea of design documentation, but in 30 years of software development experience, I've never seen one done well. TFA does a reasonably good job of outlining what you'd want from an ideal design document but doesn't offer any advice on creating one that actually meets these criteria.

One trick google uses is that there are 'standard' templates to start your design doc from. So it has all the sections mentioned in the post, and each section is initially filled with a description of what is needed there (and sometimes links to other supporting materials).

Not everyone will be diligent and fill out all applicable sections, but it does help bring some uniformity to the process.

Re: Design Docs at Google

#34

Post by thomascgalvin »

commandlinefan wrote: post #17

I like the idea of design documentation, but in 30 years of software development experience, I've never seen one done well. TFA does a reasonably good job of outlining what you'd want from an ideal design document but doesn't offer any advice on creating one that actually meets these criteria.

I think forcing a team to ask these questions is more important than making the document perfect. I've had too many conversations that amounted to "a React front-end, Node backend, Mondo data store is the perfect solution to this and every problem," with no other options chosen.

There's also value on having some this kind of documentation when you're bringing on new people. The project I'm currently working on started two years before I got here, and I would love to have a document that explained why, for example, we're using Active Directory instead of some other authentication mechanism.

Re: Design Docs at Google

#35

Post by sarchertech »

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 specificity is with code.

Design docs are closer to something a city planner would produce than to something an architect or civil engineer would, and they should be treated accordingly.

Re: Design Docs at Google

#36

Post by jhallenworld »

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.

Re: Design Docs at Google

#37

Post by shadowgovt »

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 critical mass of wizards leave the conclave, what is the company to do? Give up and shut down?)

Re: Design Docs at Google

#38

Post by cameronbrown »

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…

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.

Re: Design Docs at Google

#39

Post by sarchertech »

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.

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.

Re: Design Docs at Google

#40

Post by shuntress »

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.

That is true but if the analogy is too imperfect then it won't express the right concept.

A bad analogy is like a leaky screwdriver.

Post reply on HN