Topics

Feedback for Google's Style Guide - Images

Cameron Shorter
 

Erin, Sarah,

Do you know who maintains Google's Style Guide? I've provided feedback online, as per below. I'm wondering if it is likely to be read by someone?

--

Feedback for Images section in Google's Style Guide, at: https://developers.google.com/style/images

Hey Google,
I'm one of the contributors to TheGoodDocsProject, where we are defining writing templates for software docs. https://thegooddocsproject.dev/
For a style guide, we've selected this Google Style Guide. (Thanks for sharing it).

--

Thanks for providing a markdown example for "Text associated with images" (we have selected markdown for our base templates). Unfortunately you haven't provided markdown examples for your remaining examples. I suggest being consistent and providing markdown for all examples.

--

Re: /Make your screenshots of windows look like real windows, usually windows from a recent version of macOS unless there's a good reason to use a different operating system. For example, include the window's title bar in the screenshot. And if a given window has a drop shadow, then include the drop shadow in the screenshot as well./

I suggest that screenshots should only include background operating system window only if the instruction being described is explicitly referring to the background operating system. E.g. "Select the chrome icon to open the chrome web browser."

In all other cases, the screenshot should only include the relevant popup, or application shown on the display.

* This will help the reader find the information which is important to the step being described.

* This will help with maintenance of dated documentation, as images won't become outdated whenever operating systems are updated.

* This will help with maintaining cross-operating system documentation.

--

Screenshots can be made easier to understand by techniques such as greying out all the display, except the button that should be pressed. It comes at the expense of increasing the cost of generating the image (and maintaining it in the future). I suggest this be discussed in the Style Guide.

--

Similarly, it sometimes helps to add numbers in a bubble, sometimes with arrows between numbers, to show workflow through a screenshot. The numbers in the image can be linked to numbered steps in the text. Again, this suffers from maintenance problems, and to a lessor extent, localization problems already mentioned in the style guide. This need not be addressed in the style guide, but I'm adding here for debate.

--

I suggest that a more difficult example be selected - one that is relevant in the programming sense. (Current example is of an image with an emu foot).

How about an example of screen shot of a step in a how-to. E.g. "selecting the chrome icon". (There is a separate debate we are having around using an existing project for examples - it will likely be better to use a fictitious example.)

--

The Guide mentions: /Key Points: Use SVG files or crushed PNG images;
/

However, "crushed PNG" is not explained or even referenced in the following text. I suggest it should, and you should explain "what" and "why" use "crushed PNG", and possibly mention "how".


//


--
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254