Style Guides for Documentarians


#1

Hi,

What’s your favorite style guide? Or are they all messed up in some way?

I’m sorta splitting the “Click” v “Click on” topic, with @mdespres 's note on Style Guides.

I know Michelle cited four guides:

Microsoft Manual of Style, 4th ed (2012)
Chicago Manual of Style, 16th ed (2010)
Webster’s Third New International Dictionary (Merriam-Webster), Unabridged (2002)
Sun’s “Read Me First” 3rd ed (2009)

There are others – of course, good ole’ Strunk and White.

I personally like the GNOME Style Guide, as I think it’s best to keep such things simple. To me, a 400+ page style guide is TL:DR.


"Click" vs. "Click on"...UGH!
#2

I tried to get into the Microsoft style guide a couple years back and it was too broad for my purposes.

We ended up producing a custom one at our company that addresses just the things we care about.


#3

For advice on thorny English language questions—not for style guidelines—you can’t do better than Garner’s Modern American Usage. It is to Strunk and White what the Smithsonian is to your county historical museum. That is to say: your local museum is probably a great place for a beginner to museums to start. It was constructed with love and care and has educated generations. It’s not to be sneered at, even though it’s dusty and some of the cards have errors on them. But once your love of history has been sparked, when you want more and you’re ready to have your hair blown back, you’ll want to visit the Smithsonian, and probably spend several days there. It’s like that. You’ll be reading it for pleasure.


#4

It looks like I’ll be investing in some tax deductible reading materials, thanks to the helpful members of this community. Microsoft and Garner are top of that list, along with the 2015 AP Stylebook (which was just released this week).


#5

I think there are two different types of style guides being discussed here, and I usually cover both types in my own internal corporate style guides. One is a general writing guide (such as that which you’d find in the Chicago guide, or even Strunk & White). The other is a technology style guide that we use to help us when we document software or hardware.

That said, I also use Apple’s style guide (if you are writing for Mac or iOS products, this guide is invaluable.

And, as I commented in the thread from which this one was branched, the Sun style guide is no longer in existence, as Sun was bought out by Oracle and I don’t believe Oracle updates that doc any longer. In technology years, the six years since “Read Me First!” was last updated is a lifetime ago. Particularly if you stop to think about documenting new OSes such as Windows 8.1 and tablets, with swipes and tiles (and no real Start menus!).

P.S. Just looked, and while open source, the GNOME guide might be even older that “Read Me First!” :wink:


#6

Hi Sue,

I’m not sure that the age of a style guide is that relevant (as long as it’s < 10 years old). I like the GNOME style guide, in part, because it’s short. While the MS style guide is excellent, it’s also TL:DR.


#7

Has anyone tried incorporating a style guide into a linter?

It might not be too difficult to incorporate some corporate-specific tweaks into a scripted style guide such as Write-Good linter – just time-consuming.


#8

Thanks for the link to Write-Good, Mike! I haven’t tried it yet, but it looks helpful.

We aren’t doing any extensive, scripted style checks, but we are using schematron to do some basic style checks of topic descriptions. Right now we just check to make sure that each topic contains a description and that the description ends with a period (or an ellipsis if the description is also a link), but may add some more style checks in the future.


#9

@mikejang The reason why I bring up the age of a style guide is because, well, things progress. And our documentation should also. I am horrified at the style guides I look at that I used 20 years ago, and even 10 years ago. As our users have become more familiar with technology, we have adapted our writing. As we have become more global (in some cases), we have simplified our writing. (Obviously, if you write only developer docs, this may not apply to you.) But style guides have and should evolve and looking at something as “gospel” from a great many years ago, that was based on an operating system that has also evolved? Ten years ago, we didn’t have touch screen interfaces on computers (not reliable ones anyways). So depending on a style guide that is 10 years old could be more of a disservice to your users.

Your mileage, of course, can vary. But I personally wouldn’t use anything that is 10 years old. I’d prefer to use a more current reference.


#10

As a member of the GNOME documentation project, I can say that we’ve moved on from our own style guide. : ) There was an effort about a year or so two ago to gather people together from different open source projects and create a new, cross-project style guide, but the effort didn’t gain sustained traction.

I will try to find what I can from those efforts, though.


#11

Hi Jim,

What style guide is the GNOME project using? One thing I like about the current GNOME style guide that it’s short. Yes, “short” leaves room for interpretation, but I think that’s a good thing.

I suspect that a cross-project style guide would end up looking like another of those TL:DR 400 page bits…


#12

Hi Mike,

We’ve simplified things a bit, but I wouldn’t say that we have a professional style guide at the moment. We have a series of guide pages on our wiki, and also do a lot of peer review and mentoring with new contributors. Our situation could be improved, though.

I went back to see if I could find the beginnings of the cross-team open source style guide. Shaun McCance of Red Hat pointed me to a Gitorious repository that I’ve cloned to Github in light of Gitorious’ pending demise. The guide hasn’t been touched in some time, but we’d both be willing to put time into dusting it off if others are interested in contributing to something like this, too. We’d be open to using other formats for writing it up . . . I’m not sure why they chose HTML as the source format.


#13

Hi Jim,

The Gitorious repo is the shortest and most “to the point” style guide that I’ve ever seen.

33 lines. The longest line is 10 words.

Fantastic!


#14

Just to provide some historical perspective on the Open Help Style Guide: The idea had been tossed around for a while to have a fully open source style guide that projects (open source or not) could reference and remix for their needs. We had a sprint to start one as a pre-conference to the 2012 Open Help Conference. It included people from GNOME, Mozilla, Ubuntu, Red Hat, LibreOffice, and FreeBSD (IIRC). We surrounded ourselves with style guides, had some great discussions, and wrote a lot of stuff on very large whiteboards. Then we all went home and were too busy with everything else we do to do any significant work on it.

I still think the world needs a fully open style guide, licensed for reuse. I would still like to work on one, or even lead development of one, just not alone.

Also, though not open source, the Yahoo! Style Guide is fantastic. It’s a modern style guide that focuses on writing for the web.


#15

At the beginning of the year I did some digging into the Apache access_log for our support website, and found that the vast, vast majority of our customers were using some sort of Windows OS. So I put all my other style guides on the shelf, and have stuck with the Microsoft Manual of Style (4th edition). I use this for things like describing UI and menu elements, and as a reference on wording.

I also use the O’Reilly Stylesheet and Word List, specifically the Typography and Font Conventions section - http://chimera.labs.oreilly.com/books/1230000000969/ch03.html, and I used their Word List as a jumping off point when creating my own.

I have a copy of The Chicago Manual of Style, but damned if I know how to find anything in there. I recently purchased Garner’s Modern American Usage, and it is becoming one of my go-to references.


#16

Thanks for the link to the O’Reilly Stylesheet and Word List, Alan! While their house style is idiosyncratic, it’s comprehensive and well-considered. I’m always looking for things like that.


#17

Even though most of our customer are using Windows, I’m writing about open source software like Tomcat and JBoss and giving instructions on how to connect to Linux servers using SSH. I have several shelves full of O’Reilly titles from my days as a Linux system admin, so using their font conventions and typography guidelines just seemed natural.