Day: 2017-09-14

When will we ever need this?


It’s been a long time since I took an English course.  It would have been in my last year of high school – three mathematics, three sciences, and English.  You needed six credits and English was my fail safe.  Sorry, English teachers.

Now, I did learn a great deal going to high school and I like to think that the skills learned there continue to serve me today.  As a person who blogs every now and again, I do want to come across as somewhat literate.  Blogging does give you license to do various things that were projects in high school.  There are all kinds of things to try out.

How do I know if they’re effective?  Really, I don’t.  There’s always the kick that I get when someone writes a reply or shares a post with others.  I’m pretty sure that this is inspired by an idea I’ve shared and not as an example of the quality of my writing.  I do know that I’ve been affected by various authors on the internet and I know that periodically they do things that would have generated red ink in high school.

So, it was with more than a passing interest that I took at look at this blog post from the Google Open Source blog.

Making the Google Developers Documentation Style Guide Public

Holy Turabian, Batman.  There are standards?  Don’t people just sit down at a keyboard and hammer out instructions for their product?  Or, take the original and plunk it into Google Translate so that it becomes “English” for sale in Canada?  Could I have been right all along by asking my Computer Science students to create manuals/instructions for each program they submitted?

Google Developer Development Style Guide

I dove into this like a duck into water, like a moose to the woods, like an airplane to the sky, ….

And, you know what?

Much of this I remember from high school.  And yet, there were things that we never addressed.  I guess I just never wrote any technical manuals.  Certainly, we didn’t have a Google at the time.

How’s this for advice?

Google, Googling

  • Don’t use as a verb or gerund. Instead, use “search with Google.”

How many people have done this?  I guess it goes without saying that Googley as an adjective is out too!

Then, there’s a section about good writing.

Some things to avoid where possible

  • Buzzwords or technical jargon.
  • Being too cutesy.
  • Placeholder phrases like “please note” and “at this time.”
  • Choppy or long-winded sentences.
  • Starting all sentences with the same phrase (such as “You can” or “To do”).
  • Current pop-culture references.
  • Jokes at the expense of customers, competitors, or anyone else.
  • Exclamation marks, except in rare really exciting moments.
  • …

This is fantastic stuff.  I’m going to work my way through this and hope to learn more or just take a refresher course on writing.

If I was an English teacher, I’d have this bookmarked as the answer to the question “When are we ever going to use this?”

In the real world.  You know, the one that’s behind everything on your phone!

Advertisements

OTR Links 09/14/2017


Posted from Diigo. The rest of my favorite links are here.