Design Docs at Google • Hacker News Board

Re: Design Docs at Google

#161

Post by IOT_Apprentice » Thu, Jul 23, 2020, 12:10 AM UTC

nickbauman wrote: post #43

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…

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. And this is why Software development should never be considered engineering. Architecture is important and in the construction phase there are changes and revision to the design that are captured and formally reviewed.

In software, if the code is the "design" then it should be a priority for computer science to agree upon a standardized design representation (UML) that can be generated by the compiler/interpreter, along with code coverage and static analysis.

The issue here is that there has not been adoption of formal rigor of design and definition of implementation into code of proof of correctness alongside data structures and algorithms appropriate to the domain state. Add in understandable and usable build and testing tools.

The infrastructure is there, with CI/CD, and a repository of github/gitlab, team foundation, cvs code and say something like a successor to GPT3 to do the grunt work of analyzing code to determine optimal patterns of implementation vs existing code bases and development sprint branches.

Even compiling code or "making" it can be a crapshoot for extremely senior and competent developers.

Some food for thought.

Re: Design Docs at Google

#162

Post by andromeduck » Thu, Jul 23, 2020, 12:32 AM UTC

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…

Yeah it's in this really weird niche between the more simple text/note oriented markdown and the more print oriented word/pages. Like if it needs to look good when printed word is way superior but for simple things that don't, markdown is almost always better unless you want to solicit feedback or do live collab. And that's great, collab was definitely the killer feature a decade ago but who really still needs to print? It seems most Schools don't even take paper assignments anymore and nearly everyone has access to a phone/printer + internet so what's even the point of putting so much emphasis on print? I wish it would evolve to focus be more digital first experience with some reader-mode esque simplification or print hints like page breaks and the like if someone really wants to print.

Re: Design Docs at Google

#163

Post by winrid » Thu, Jul 23, 2020, 12:33 AM UTC

At a medium sized company/startup that follows this pattern. It works really well.

Much better than the core platform team just going and changing a bunch of stuff every release with no documentation, which I've experienced consistently at my last job.

Re: Design Docs at Google

#164

Post by sfifs » Thu, Jul 23, 2020, 12:49 AM UTC

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.

Re: Design Docs at Google

#165

Post by m0zg » Thu, Jul 23, 2020, 1:16 AM UTC

influx wrote: post #157

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 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 able to "take credit" - it's easier to just "lead" a project which is already on its way to getting launched by sitting in meetings with people more senior than you.

You get _nothing_ for improving things that already exist. As a result you get four different messaging apps, and not a single one that doesn't suck, and a bunch of stagnating, seemingly abandoned products. The reason is simple: people who are smart enough to understand the rules of the game move on immediately after launch to the next big thing.

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

Re: Design Docs at Google

#166

Post by dllthomas » Thu, Jul 23, 2020, 2:42 AM UTC

supahfly_remix wrote: post #53

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.

If the design is the code, then what is a bug? There is a separate model, whether written down or not, of what the code must do. That is the deaign.

No, that is the requirements.

Re: Design Docs at Google

#167

Post by mkoubaa » Thu, Jul 23, 2020, 2:46 AM UTC

TeMPOraL wrote: post #147

javier10e6 wrote: post #124

Earlier quoted context omitted.

I agree wholeheartedly. The best software documentation is the an actually well written software module + test that explains its functionality.

Let's not forget about comments. A well written piece of code will only tell you what it does, a good suite of tests will teach you how to use it, but only natural language documentation - be it in comments or separate documents - will explain to you why the code exists in the first place, and why it looks the way it does. (As for "self-documenting code", unless a lot of your functions contain the word "because" in t…

in summary: what -> naming convention why -> comments how -> tests

I wish this was more commonly shared and understood

Re: Design Docs at Google

#168

Post by galkk » Thu, Jul 23, 2020, 2:50 AM UTC

akhilcacharya wrote: post #136

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 company we use the internal Wikis or Quip for this. Versioned and effectively markdown formatted with builtin live charts or spreadsheets, respectively.

Amazon had both wiki and Quip, and both were bad, but differently.

Wiki was painfully slow to edit (and render, ~2 sec page render was typical, and I'm not counting some graphs that were asynchronously rendered).

Quip is good for fast editing, but anything that needed code formatting there is bad. It's even more "print oriented" than Google docs. Fixed page width, very fixed formatting, tables are awful.

Re: Design Docs at Google

#169

Post by blululu » Thu, Jul 23, 2020, 3:16 AM UTC

This is a very optimistic presentation of design docs. The flip side is that these documents can become a touchstone for bike shedding or and excuse to make slideware in lieu of software. A lot of administrative bloat can creep in through design docs.

Re: Design Docs at Google

#170

Post by Aperocky » Thu, Jul 23, 2020, 4:14 AM UTC

eitally wrote: post #29

Aperocky wrote: post #5

Earlier quoted context omitted.

> I know this is fairly controversial, but our jobs isn't just to write code. I don't know if this is actually controversial, but I would not want to work at a place where this is controversial.

I think -- from experience -- that in traditional IT organizations this is absolutely not true. The PMO is responsible for business requirements, and almost not time is invested in the creation of detailed DDs. You're essentially left trying to move from a PRD to writing code ... and if you have the luxury of an in-house SQA team and a relatively effective CI/CD process, you depend on quick feedback from stakeholders…

Yeah that read like a lot of baggage, some of the term I'm not even familiar with (SQA, DD?)

As it stands now, we take high level feature design docs from PM, and turn them into service. Everything between that, resources, development, operations are handled entirely in team where everyones title is SDE. This placed a lot of communication, writing, designing on us but I'm not complaining.