What's new

Each week, we update this page with a summary of recent significant changes to the style guide. If there haven't been any significant changes in a given week, we don't publish updates.

June 29, 2020

On several pages, reorganized guidance about formatting code and command lines. In particular:
- Moved the guidance that was in a page about command-line terminology to the Documenting command-line syntax page, and deleted the separate command-line terminology page.
- Moved the guidance about placeholders to a new Formatting placeholders page.
- Added cross-references among various code-related pages.
In the word list, corrected a typo.

June 22, 2020

In the word list, changed guidance about using earlier and later for a range of version numbers.

June 15, 2020

On the Capitalization page and other pages, made guidance consistent about capitalizing references to document titles.
On the Cross-references page and other pages, added guidance about not forcing a link to open in a new tab.
On the Code in text page, added guidance about when to put UI elements in code font.
Added an entry to the word list: best effort.

June 8, 2020

On the Writing inclusive documentation page, added guidance about avoiding figurative language that relates to the slaughter of animals.

June 1, 2020

On the Figures and other images page, updated guidance about alt text, figure descriptions, and figure captions.
Reorganized the HTML and semantic tagging page, and added guidance about not using the <br> element to change visual presentation. Also replaced a broken link to a third-party site.
On the Numbers page, added guidance about avoiding using Roman numerals.
Added entries to the word list: currently, dash, NoOps.

May 25, 2020

On the Numbers page, corrected two examples to match our guidance.
On the Abbreviations page, added guidance about use of the term acronym.
Added entries to the word list: happiness, scale, service level agreement, service level indicator, service level objective. Also clarified guidance for app.

May 18, 2020

On the Filenames and file types page, added guidance about how to refer to a filename.
On the Headings and titles page, updated the guidance about using code font in headings.
On the UI elements and interaction page and elsewhere, replaced the term arrow notation with angle bracket.
On the Procedures page, clarified the guidance about stating the location of an action before stating the action.
Added entries to the word list: config, extract, unarchive, uncompress, untar. Also changed the guidance about ssh and related terms. Also corrected a typo.

May 11, 2020

Major change: On the Code in text page, changed guidance for placeholder styling. The new preferred style is all-uppercase with underscore delimiters.
Also on the Code in text page, corrected guidance about how to mark up placeholders with Markdown.
On the Figures and other images page, corrected a typo.

May 4, 2020

On the Second person and first person page, clarified guidance about when to use implicit you.
On the UI elements and interaction page, added guidance about toggle.
Added entries to the word list: dashboard, master. Unrelatedly, fixed a longstanding word list typo.

April 27, 2020

On the Documenting command-line syntax page, added guidance about showing the output of commands.
On the Example domains and names page, added example IPv6 addresses.
On the Words as words page, clarified guidance.
In the word list, clarified guidance for the word following. Also clarified guidance for the various console terms.
Added an entry to the word list: native.

April 20, 2020

On the Units of measurement page, added guidance about using per when referring to rates.
On the UI elements and interaction page, clarified the distinction between text input and keyboard shortcuts, and added guidance about when to use the <code> and <kbd> elements. On the Code in text page, added text input to the list of things to put in code font.
On the Accessible content page, added a recommendation to use a screen reader to test your documentation. Also added guidance about introducing tables.
On the Example domains and names page, changed the recommended example company names to avoid camel case.
On the Code in text page and the Colons page, clarified and expanded guidance about how to format a colon after text that's bold or in code font.
Added entries to the word list: key, key ring, per, vice versa.

April 13, 2020

On the Lists page, expanded the guidance about when not to use sentence-ending punctuation.
Added cross-references between the Abbreviations page and the Headings and titles page.
On the Numbers page, clarified the guidance about hyphens and en dashes in ranges of numbers.
On the Units of measure page, clarified guidance about what counts as a unit.
In the word list, clarified guidance about using blacklist and whitelist.
Added entries to the word list: ad tech, easily, fintech, NLU, quick, quickly.

April 6, 2020

On the Abbreviations page, clarified guidance about using abbreviations in headings and titles.
On the Text-formatting summary page, added guidance on formatting mathematical variables.
On the Link text page, added guidance about abbreviations in link text.
On the Dates and times page, added guidance about how to express time zones.
In the word list, clarified guidance about key-value pair.
Added an entry to the word list: personally identifiable information (PII).

March 30, 2020

On the Hyphens page, clarified guidance about ranges of numbers.
In the UI elements and interaction page, changed guidance for formatting input for text boxes to recommend using the HTML <code> element instead of <kbd>.

March 23, 2020

On the Capitalization page, made the following changes:
- Removed outdated guidance about capitalization after a run-in heading. For the current guidance, see "Description lists that use run-in headings" on the Lists page.
- Clarified guidance about avoiding all-uppercase and camel case.
- Clarified guidance about avoiding lowercase at the start of a sentence.
- Clarified guidance about capitalization when referring to documents by title in various contexts.
Expanded and reorganized the Code in text page. In particular:
- Expanded the guidance about documenting placeholders.
- Expanded the list of items to put in code font.
On the Commas page, added guidance about using a comma with because.
On the Dashes page, added guidance about not using en dashes.
Added entries to the word list: datastore, tutorial. Also added guidance (in the entry for documentation) about phrases like in this document.

March 2, 2020

On the Capitalization page, added guidance about using sentence case for labels and callouts.
On the Cross-references page, added guidance about how to format the titles of web series.
Added an entry to the word list: web server.

February 24, 2020

On the Resources page, added links to the Kubernetes glossary and the Kubernetes style guide.
On the Lists page, added guidance about how and when to use a bulleted list with run-in headings.
Updated the word list to refer to Google Cloud instead of GCP, in accord with a recent name change. In particular, changed entries for GCP, GCP Console, and GCP project ID to Google Cloud, Google Cloud Console, and Google Cloud project ID, respectively.
Added an entry to the word list: GKE node. Also updated guidance for GKE.
In the left nav, moved the word list and the product-names page to near the top.
On the Plurals in parentheses page, added guidance about using the phrase one or more.

January 13, 2020

In the Writing for a global audience page, fixed a broken link.
In the Code in text page, added environment variable names to the list of items to put in code font.
Added entries to the word list: A/B testing, BGP.

January 6, 2020

Added entries to the word list: DevOps, ECMP, GFE, NoSQL, PostgreSQL. Also updated guidance on virtual machine (VM) instance.

December 23, 2019

Expanded and clarified the Writing for a global audience page.
Renamed the "Typographical conventions" page to "Text-formatting summary."
On the Tables page, clarified guidance about punctuation in table column heads.
On the Filenames and file types page, added .jar to the list of filename extensions.
On the UI elements page and the word list, clarified guidance about when to use box and field to refer to text boxes.

December 16, 2019

On the Abbreviations page, expanded guidance about when to spell out abbreviations.
On the conventions page, fixed two broken links.
Added entries to the word list: as, big-endian, google.dev, little-endian.

December 9, 2019

On the Tables page, added guidance about sorting tables, and clarified guidance about when to use tables.
Reverted last week's changes about using earlier and later instead of lower and higher; those changes need further refining.

December 2, 2019

On the Cross-references page, added guidance about using the word about in cross-references, rather than on.
Added entries to the word list: about versus on, for instance, SLA. Also changed guidance about using earlier and later for a range of version numbers.

November 25, 2019

On the UI elements and interaction page, added guidance about focusing on the task rather than on UI elements as such.
On various pages, added cross-references linking to other pages.

November 18, 2019

Added a new Typographic conventions page.
Reorganized the Units of measurement page. Also added guidance about Kelvin temperatures.
On the Cross-references page, clarified guidance about cross-references that aren't links.
On the UI elements and interaction page, added information about expander arrows.
Added a term to the word list: slice and dice.

November 11, 2019

On the Figures and other images page, clarified guidance about figure descriptions.
On the Units of measurement page, added guidance about ranges of numbers.
On the Product names page, clarified guidance about using full trademarked product names.
Added terms to the word list: billing charges, port, repo, UI.

October 28, 2019

Added guidance about what to do if there's more than one way to complete a task.
Added terms to the word list: just, multi-tenancy.

October 21, 2019

Added a page about formatting words as words.
Added a page about formatting key terms.
Changed the guidance about how to capitalize a UI element name when the label is all-uppercase in the UI.
Added guidance about explaining placeholders.
Updated the list of items to put in code font.
Clarified the guidance about using official capitalization for names of products.
Changed the title of the style guide landing page.
Deleted the page about URLs in links, and moved the material that was on that page to the cross-references page. Also added some examples to that page.
Removed unnecessary explanations of the icons that indicate that a guideline applies only in Android documentation or only in Google Cloud Platform documentation.
Added examples to the footnotes page.
Improved a link on the Accessible content page.
Added terms to the word list: BMaaS, US.

October 8, 2019

Reorganized the page about notices, and added examples.
Cleaned up some minor formatting and phrasing issues in the word list.
Corrected a typo on the Accessible content page.
Changed the title of the style guide to use sentence case.

September 30, 2019

Added a term to the word list: PoP.

September 23, 2019

Added a page about footnotes.
Reorganized the Other editorial resources page.

September 16, 2019

Added a page about using material from other sources.
Added guidance about using a and an with product names.
Removed contradictory guidance about quotation marks with link text.
Clarified guidance about periods with abbreviations.
Clarified guidance about capitalization following a colon.
Moved the list of UI-related verbs from the UI elements page to the word list.
Also added other terms to the word list: cons, Gbps, Kbps, Mbps, pros. Also updated the entry for service.

June 24, 2019

Added guidance about US currency to the Numbers page.

June 17, 2019

Added further guidance about accessibility to the Accessible content page and other related pages.
Added guidance about graphically violent terms to the Writing inclusive documentation page.
Added guidance about the term wheelchair-bound to the Writing inclusive documentation page.
Added guidance about currency to the Units of measure page.
Added an example showing how to use Markdown to mark up images.
Added terms to the word list: disclosure triangle, hamburger menu, kebab menu, outpost, STONITH. Also expanded guidance about should.

May 20, 2019

Added a new page about avoiding excessive claims.
Added material about file types to the Filenames and file types page.
Added terms to the word list: CSV, traditional, YAML.

April 29, 2019

Replaced the guidelines on the Accessible content page with a new set of more relevant guidelines.
Added a term to the word list: execute.
Added material about Linux signals on the Command-line terminology page, and updated related entries in the word list.

April 22, 2019

Added a term to the word list: method. Also added to the guidance for Cloud.

April 15, 2019

Added more guidance about digit-group separators on the Numbers page.
Fixed a broken link on the Numbers page, and another on the Writing for a global audience page.
Updated guidance about example names on the Example domains and names page.
Added guidance about removing personally identifying information from screenshots on the Figures and other images page.
Added guidance about using code font for names of command-line utilities on the Code in text page.
Added guidance about short and long versions of words like app and demo on the Abbreviations page.

March 4, 2019

Clarified guidance about person-first and identity-first language on the Writing inclusive documentation page.
Added guidance about passive voice on the Active voice page.
Added more guidance about links on the Linking to other sites page.
Added terms to the word list: guru, spin up. Also revised the guidance for Container Engine.

February 25, 2019

Added extensive new material to the inclusive documentation page.
Updated the word list:
- Clarified guidance for argument and flag.
- Added terms: allows you to, desire, drop-down, wish.
- Removed the recommendations against using enable and disable, and clarified guidance for those terms.

February 4, 2019

Added terms to the word list: add-in, add-on.
Added guidelines about avoiding repetitive procedures.

January 28, 2019

Updated the word list:
- Changed guidance for above and below.
- Added terms: gcloud, ML.
- Updated guidance for &.
- Improved alphabetization.
Fixed a broken link in the Lists page.

January 14, 2019

Added terms to the word list: comprise, console, fail over, GCP Console, Google Cloud Platform Console, populate, surface.
Reorganized the UI elements page, and added guidance and examples.
Added Markdown information to the URLs for images page.
Clarified guidance about end punctuation for lists on the Periods page.
Clarified guidance about nonbreaking spaces in the Units of measurement page.

December 3, 2018

Added a term to the word list: lifetime.
Elaborated on our guidance in the Closed compounds and prefixes section of the word list.
Added a new page about command-line terminology for gcloud and Linux.
Added a section on straight and curly quotation marks to the Quotation marks page.
Added guidance about avoiding overuse of bolding to the Procedures page.
Added guidance about the phrases hold the pointer over and point to to the UI elements and interaction page.

October 29, 2018

Added terms to the word list: blacklist, whitelist.
Reorganized the dates and times page, and added guidance about times and about ISO 8601.

October 8, 2018

Added recommendations for example company names.
Added guidance about using monospace formatting to the UI elements and interaction page.
Added guidance about giving the location of an action in a procedure to the Procedures page.

September 18, 2018

Added terms to the word list: GKE, POJO.

September 4, 2018

Added guidance about cases where filenames aren't under your control.
Added a term to the word list: big data.

August 13, 2018

Added guidance about avoiding internet slang.
Added terms to the word list: multi-cloud, RTFM, tl;dr, ymmv.

July 30, 2018

Added terms to the word list: disaster recovery, file system, high availability, high performance computing, OS, tarball, tar file.
Updated guidance in the word list for on-premises.
Rephrased a paragraph of the landing page.

June 25, 2018

Added terms to the word list: IP, SAP.

June 19, 2018

Added a term to the word list: trojan.
Improved the organization, formatting, and phrasing of the filenames page.

June 12, 2018

Added terms to the word list: appendix, index, matrix.

May 21, 2018

Changed the guidance about how to link to Android reference documentation.
Added information about using the with product names.
Added a note about indefinite and casual numbers to the Numbers page.
Fixed a broken link on the authorial tone page.

May 14, 2018

Added terms to the word list: multi-cluster, via. Clarified guidance on firewalls.

April 2, 2018

Added a page about writing inclusive documentation.
Added terms to the word list: at scale, IAM, RFC.

March 26, 2018

Added information about alt text for decorative images to the images page.
Added terms to the word list: fill in, fill out, microservices.

February 26, 2018

Added a term to the word list: ad hoc.

February 12, 2018

Added terms to the word list: Cloud, Container Engine, ephemeral external IP address, firewalls, GCP, GCP project ID, internal IP address, NAT, network IP address, non-key, on-premises, persistent disk, project, RDP, static external IP address, subnet, table name, textbox, turn on.
Added information about closed compounds and prefixes to the word list.

January 29, 2018

Added terms to the word list: alpha, autohealing, autoscaling, autotagging, bare metal, beta, CLI, Cloud SDK, colocate, CPU, curated roles, data center campus, data cleaning, data source, ETL, IaaS, impact, ingest, k8s, key pair, PaaS, preemptible, regex, SaaS, screenshot, sign-in, sign into, sign-out, sub-command, v, virtual machine instance.
Added a section on placeholder variables to the code in text page.

January 8, 2018

Added terms to the word list: argument, backup, dataflow, flag, higher, later, long press, multi-region, option, slave, touch & hold, transpile, wildcard.
Added an item (DNS record types) to the list of items to put in code font.

December 11, 2017

Added material on numerical dimensions.
Added material about possessives of company and product names.
Added terms to the word list: docset, documentation, startup, sync.

November 13, 2017

Changed guidelines on end punctuation for list items.
Added alphabetical headings to the word list, so you can now jump to a specific letter using the in-page TOC.
Updated word list entries for error-prone, real time, and Search.
Added terms to the word list: dataset, legacy, nonfatal.

October 23, 2017

Added a new page about plurals in parentheses.
Added a link to the C++ coding style guide, in the Coding style guides section.

September 4, 2017

Added several more terms to the word list: check, checkbox, clear, deselect, open source, select, target, uncheck, Unix-like, unselect.
Added material to the Trademarks page about using trademarks as adjectives. Also added links to a couple of other trademark-related pages from Google.
Removed Android-specific material from the Headings page, to bring Android doc guidelines more into line with non-Android guidelines. Also, added notes about things not to include in headings.
Removed Android label from material on the Tables page, to make that material also apply to non-Android docs.
Added mention of degrees and percents to the Units of measurement page.

August 28, 2017

Added 160+ terms to the word list. (Too many to list here.)
Added recommendations for image size and placement to the Images page.
Moved material about Javadoc links to the Code in text page.

August 21, 2017

Added new File names page.
Added new Units of measurement page.
Changed "internet" to lowercase.
Added material about line lengths and Javadoc-style links to the HTML formatting page.

July 31, 2017

Added new Headings and titles page, mostly focused on Android documentation.
Added information about tables in Android docs to the Tables page.

July 10, 2017

Added words to the word list: deep linking, jank, wake lock.

June 8, 2017

Public release.