Style Guides

As many of you reading this already know, I am a writer. I write for a living. I write technical documentation, books, occasional articles for magazines and websites, and more. The books in this post have been helpful to me primarily in technical writing.

Style guides exist to help writers reduce the number of decisions they must make as they write. This simplifies the complex task of writing technical documentation, at least a little, by eliminating many of the questions that a good writer must ask. Should my directions use the word “click” or “open” when referring to using the mouse to start a program? Should menu options be set off in sentences using italics or bold text? For many of these sorts of questions, there is no right or wrong answer, there is rather a strong need to choose a form and use it consistently. For other questions, there are strong reasons to choose one format or expression over another, but these are not always easy to remember. This is where style guides help.

The first style guide I used, and which still sits on my desk, is The Chicago Manual of Style, which has been around since the late 1800s. Published by the University of Chicago Press, this manual has been a consistent and well respected guide to good writing for decades. While there is a newer edition available, both in print and online, I still have the 15th Edition sitting on my desk, and it has served me well. However, this is a general-purpose style guide, and most of what I write lately is focused on computer software, which uses terminology not covered by The Chicago Manual of Style. I needed to look further.

The rest of this post will focus on three style guides intended for the computer industry. Each of them cover the vital information a technical writer will need when covering topics related to computers, both hardware and software. These include writing mechanics, formatting, style, procedural directions, writing for an international audience, and so on. They differ primarily in the choices made and the manner in which they themselves are written.

Read Me First! A Style Guide for the Computer Industry, 3rd Edition came out in 2010. It was published by Sun Technical Publications, which was part of Sun Microsystems. The style is easy to read and clear, not too dry and never frivolous. The book gives clear examples and labels them “correct” and “incorrect” to help the reader. I have used this book for about 18 months and it has served me well. Some unique topics in this book include legal guidelines for protecting copyrights and trademarks, and a description of different types of technical documentation. This is a very good style guide, but I wonder about its future, since Oracle’s purchase of Sun Microsystems was completed a few months after this edition was published.

The IBM Style Guide: Conventions for Writers and Editors came out in 2012. This is the first edition of the book, but it seems safe to assume IBM has had an internal style guide for decades. IBM documentation is always clear, well written, and consistent. This book is formal, always appropriate in tone and style, and gives many examples to show the “correct” and “incorrect” way to express content. This is a style guide worthy of use by anyone who wants to produce professional documentation.

Microsoft Manual of Style, 4th Edition came out in 2012. This style guide surprised me, in several good ways. First, the layout uses more white space, a clearer typeface, and is slightly easier to read than most style guides. It isn’t that the others are bad, but that this one is better. I also like that Microsoft does not label their examples as “correct” or “incorrect,” but instead uses the terms “Microsoft Style” and “Not Microsoft Style.” While it should be understood that this is the ultimate meaning of “correct” and “incorrect” in the books from IBM and Sun, Microsoft comes across as both authoritative and humble at the same time–an impressive feat. Unique topics include writing with accessibility in mind, for content reuse in ways that allow those with non-traditional needs to be able to use the information.

Bottom line

The Chicago Manual of Style is a writer’s standard, but does not explicitly cover the needs of technical writers creating documentation for computer hardware and software. Each of the other three books mentioned here is a quality guide to creating useful documentation that is clear, useful, and appropriately standardized. They all cover the most important topics, but some of them have information not covered by the other two. Using any of the style guides listed here will benefit the technical writer, especially if no style guide is currently being used. If I was starting a new project, I would probably choose the Microsoft style guide, but I want to be clear that all of them are adequate to the task and worth a look if you are seeking guidance.

Disclosure: I was given my copies of Read Me First!, The IBM Style Guide, and Microsoft Manual of Style by the publishers as review copies. I bought my copy of The Chicago Manual of Style years ago when I first got started.

I cut my hair for cancer

Until yesterday, my hair was very long. It had grown down well below my shoulders. I cut it so that my hair can be made into a wig for cancer patients who have lost their hair as a result of treatment. There are many ways you can do this; I chose to donate via the Pantene Beautiful Lengths program. Here are a few pictures that my daughter took. These are thumbnails, click to view a large version.

Idea I don’t have time to pursue

There should be a blog called There was a meeting about this where every post shows something that was approved, created, and marketed but which causes normal people to scratch their heads and wonder why in the world this thing exists.

Reading up on HTML5 and CSS3

Everyone is talking about HTML5 and CSS3. If you believe the hype, they will change how web development is done while feeding the world and creating new opportunities for people everywhere to enjoy a new era of peace, love, and rainbow-emitting unicorns. Obviously, I’ve been around long enough to be a skeptic.

That said, I do want to keep up on standards and trends, if only to keep my work from causing me embarrassment and to prevent having to do more work than necessary (by having to perform updates soon after code is written). With this in mind, I picked up two books on HTML5 and CSS3.

First, I read Pragmatic Programmer’s HTML5 and CSS3: Develop with Tomorrow’s Standards Today by Brian P. Hogan.

I liked this book. It was easy to read and understand. I liked that the book avoids hype and marketing speak and sticks to a clear description of HTML5 as a platform and as a specification. The author respects his intended audience, presumably people who are currently involved in web design and development and who don’t need their hands held with very basic descriptions of JavaScript, jQuery, or basic HTML and CSS from past versions. This book focuses on the new features that are most likely to be useful and exciting to developers: new structural tags and attributes, improved methods for creating web forms, making better interfaces, improving accessibility, and, of course, eye and ear candy in the form of canvas and media embedding.

Next, I read Sitepoint’s HTML5 & CSS3 For The Real World by Alexis Goldstein, Louis Lazaris, and Estelle Weyl.

This book is also intended for people with experience using HTML and CSS. The basics are often assumed and not covered in great depth. This means that most of the book is dedicated to things the target audience does not already know. In addition, this book also avoids the hype and unicorns and focuses on specific aspects of HTML5 and CSS3 that will be most useful to real world developers. The book includes a real world style example that is used to introduce the similarities and differences in the new versions of HTML and CSS that will make it easy for people familiar with the technology to jump in and do something practical.

HTML5 & CSS3 For The Real World covers all the same basic material as HTML5 and CSS3: Develop with Tomorrow’s Standards Today, but with some very useful and appreciated additions. Here we have coverage of Modernizer, a JavaScript library that can test for individual HTML5 features in a browser rather than simply checking what browser is being used, WAI-ARIA for making websites accessible more easily, and the Microdata Specification that allows machine-readable data to be embedded in HTML documents. Cool stuff!

Bottom line: both books are good, but HTML5 & CSS3 For The Real World covers more features and does so using better examples. I’ll give it a 5/5 and rate HTML5 and CSS3: Develop with Tomorrow’s Standards Today a very close second at 4/5.

Disclosure: I was given my copy of each of these books by the publishers as review copies.