'Don't Google Google, Googling Google is wrong', says Google
Chocolate Factory unwraps developer style guide, squibs the thorny ISO date debate
Posted in DevOps, 13th September 2017 06:01 GMT
If you want to write developer documentation like a Google hotshot, you'd better kill “kill”, junk “jank” and unlearn “learnings”.
Those are just a few rules from the company's newly open-sourced (oops, two sins there, verbing and hyphenation) developer documentation guide.
Even though any Linux user knows “kill” is a command, Google would rather you not use it as a verb – “stop,” “exit,” “cancel,” or “end” are preferred. “Jank” (Wiktionary says “blocking of a software application's user interface due to slow operations or poor interface design”) should be used with care; and thankfully, “learnings” get a simple “don't use”.
And yes, what we said in the headline is correct. Google's style gurus have ridden out in a crusade against verbing the corporate noun: “Don't use as a verb or gerund. Instead, use 'search with Google'” (we consider it admirable that Mountain View expects “gerund” to get by without a developer Googling it – sorry, “searching it with Google”).
The guide carries plenty of evidence of a long debate about what words can be both noun and verb: “login” is a noun, with “sign in” given as the preferred verb; “backoff (noun), back off (verb), back-off (adjective)” are noted; "clickthrough/click through" are similarly stipulated; and “display” is troublesome because it's intransitive (Google it. Damn, we broke the rule again, we meant “search 'intransitive' with Google”).
“Interface” gets similar treatment: if you're reaching for a verb, the preferred list is: interact, talk, speak, or communicate.
As anyone who's tried to draft a style guide will tell you, contradictions are inevitable. So it is that “the Internet” has turned into “the internet” because other style guides (thank you very much, The Guardian) do so. However, just a couple of lines down, we find that the “internet of things” is rendered “Internet of Things” to explain why IoT is an acceptable abbreviation.
And that's just a sampling the word list. Punctuation, grammar and syntax would make pedants everywhere proud, we guess.
The Oxford Comma, controversial almost anywhere, is given Google's blessing (although not named):
Not recommended: I dedicate this book to my parents, Ayn Rand and God.
Recommended: I dedicate this book to my parents, Ayn Rand, and God
… and we learn that Google follows the usage of all civilised persons: it instructs devs not to capitalise the first word after the colon.
As an American company, Google can't risk a howl of outrage by enforcing ISO date formats over the locally-preferred Month:Day:Year. Instead, it asks me to state that this article was written on September 13, 2017.
We're sure that our readers will find many more amusements, outrages, and debates in the guide. Let us know what you find in the comments. ®