5 ms·

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

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 text (e.g. code), has basically no support for mathematical formulas, etc. In fact its actually evolved to be less suited to the task of technical documentation since it began given that earlier versions at least allowed you to define your own paragraph styles. I was hoping that Google Colab might evolve into a better/more general tool for writing tech specs but it doesn't seem to be moving in that direction really.

maxwellg 6y ago
Comment discovery is also horribly broken. So often, conversations _about_ a document contain information that don't necessarily _belong in_ the document, but still have value for future readers. Resolving comments makes it much harder to find them.
xnx 6y ago
Exactly correct about the print-oriented interface. Writely, and earlier versions of Google Docs didn't force you to pretend you were writing on a piece of paper. I would love a "Google Docs for text files"!
akhilcacharya 6y ago
At my company we use the internal Wikis or Quip for this. Versioned and effectively markdown formatted with builtin live charts or spreadsheets, respectively.
- galkk 6y ago
  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.
lazyant 6y ago
Yep. Add to the list: no Markdown support.
influx 6y ago
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!
- m0zg 6y ago
  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.
  - m463 6y ago
    That seems to agree with what a friend of mine who worked there, and how he was rewarded (or not). I can't help but think they are rewarding the right thing -- new shiny things may have the best ability to bring stragglers onto google the platform. Unfortunately, it leads to the feeling that google just dabbles in things.
  - pradn 6y ago
    That's a popular perception but it's not totally true. You need to be able to measure improvements you make, which might make a large category of possible improvements untenable from a perf point of view. But if you can show satisfaction scores or latency numbers or action-conpletion metrics or even just customer comments saying it solved their issue, that's plenty reason to attempt the change. The system encourages you not to work on things that "feel good" but instead things that are measurable. There's pros and cons to this as you can imagine. That all said, I think the bigger problem is a willingness to put out things that don't meet a high standard. Ex: the new web GMail launched while slower than the older one. This was done to get new features out to users faster, but it doesn't feel that great from a product excellence POV. There's no Steve Jobs figure telling us the Pixel 4 doesn't look great and as a consequence we should go back to the drawing board. It's more like there's a set of market survey results and the phone was made to check those boxes.
flarg 6y ago
On the other hand I love the simplicity of Google Docs and we use it for everything at my (very large) employer and it's particularly suited to collaboration between technical people and business people. The familiar document interface works for the business folk whilst the ability to add and assign tasks as comments makes the whole experience seamless.
__float 6y ago
Have you tried Dropbox Paper? Unlike what the name implies, it's the most non-print-focused editing experience I've used. Anecdotally, it's much more popular for design docs than Google Docs at my current employer.
andromeduck 6y ago
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.
sfifs 6y ago
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.
- noir_lord 6y ago
  My experience as well - We are all in on Atlassian. Confluence is brillient, bitbucket is meh but OK and JIRA is an utter tire fire both in how it's built and what it does but PHB's and PHB-shaped objects love it.
ciconia 6y ago
I think the target audience is mostly non-programmers AKA normal people. It's a general-purpose tool hence the feature set.
amf12 6y ago
> One thing that has always surprised me about documentation at Google is that they use Google Docs When did you work at Google? There are markdown supported wiki tools now for internal documentation. It supports pre-formatted code, graphs, etc.

maxwellg 6y ago

Comment discovery is also horribly broken. So often, conversations _about_ a document contain information that don't necessarily _belong in_ the document, but still have value for future readers. Resolving comments makes it much harder to find them.

xnx 6y ago

Exactly correct about the print-oriented interface. Writely, and earlier versions of Google Docs didn't force you to pretend you were writing on a piece of paper. I would love a "Google Docs for text files"!

akhilcacharya 6y ago

At my company we use the internal Wikis or Quip for this. Versioned and effectively markdown formatted with builtin live charts or spreadsheets, respectively.

galkk 6y ago
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.

lazyant 6y ago

Yep. Add to the list: no Markdown support.

influx 6y ago

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!

m0zg 6y ago
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.
- m463 6y ago
  That seems to agree with what a friend of mine who worked there, and how he was rewarded (or not). I can't help but think they are rewarding the right thing -- new shiny things may have the best ability to bring stragglers onto google the platform. Unfortunately, it leads to the feeling that google just dabbles in things.
- pradn 6y ago
  That's a popular perception but it's not totally true. You need to be able to measure improvements you make, which might make a large category of possible improvements untenable from a perf point of view. But if you can show satisfaction scores or latency numbers or action-conpletion metrics or even just customer comments saying it solved their issue, that's plenty reason to attempt the change. The system encourages you not to work on things that "feel good" but instead things that are measurable. There's pros and cons to this as you can imagine. That all said, I think the bigger problem is a willingness to put out things that don't meet a high standard. Ex: the new web GMail launched while slower than the older one. This was done to get new features out to users faster, but it doesn't feel that great from a product excellence POV. There's no Steve Jobs figure telling us the Pixel 4 doesn't look great and as a consequence we should go back to the drawing board. It's more like there's a set of market survey results and the phone was made to check those boxes.

flarg 6y ago

On the other hand I love the simplicity of Google Docs and we use it for everything at my (very large) employer and it's particularly suited to collaboration between technical people and business people. The familiar document interface works for the business folk whilst the ability to add and assign tasks as comments makes the whole experience seamless.

__float 6y ago

Have you tried Dropbox Paper? Unlike what the name implies, it's the most non-print-focused editing experience I've used. Anecdotally, it's much more popular for design docs than Google Docs at my current employer.

andromeduck 6y ago

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.

sfifs 6y ago

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.

noir_lord 6y ago
My experience as well - We are all in on Atlassian. Confluence is brillient, bitbucket is meh but OK and JIRA is an utter tire fire both in how it's built and what it does but PHB's and PHB-shaped objects love it.

ciconia 6y ago

I think the target audience is mostly non-programmers AKA normal people. It's a general-purpose tool hence the feature set.

amf12 6y ago

> One thing that has always surprised me about documentation at Google is that they use Google Docs When did you work at Google? There are markdown supported wiki tools now for internal documentation. It supports pre-formatted code, graphs, etc.