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 am the sole editor and contributor of new content for the just-released Ubuntu Unleashed 2012 Edition. This book is intended for intermediate to advanced users.

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.

I had the privilege to lead the team that updated The Official Ubuntu Book for this sixth edition. The book continues to serve as a quality introduction for newcomers to Ubuntu, both the software and the community that surrounds it.

ISBN-13: 978-0132748506

Link to the Amazon.com page for the book.

It has again been a while since I have reviewed a manga book. This is one of several atypical educational books that use graphic art to help teach difficult concepts or illustrate the action and another wonderful entry in the “Manga Guide to…” series that I have been reviewing.

The Manga Guide to Relativity follows the actions of a high school class president who steps in to save the rest of the students at the school who were being threatened by the school headmaster with a punishment for their lack of scholastic success. To save them, the brave student leader agrees to take a special summer course on relativity and write a report for the headmaster. The student doesn’t know what relativity is, but a kind and attractive teacher volunteers to teach him all about it. The story line is okay, but not as good as some of the other stories in the series. However, it still succeeds in its main task of easing the reader into the topic.

The book covers all the main questions and topics you would expect such as the definition of relativity, the Urashima Effect (where times slows down as speed approaches the speed of light), mass and the contraction of length (again, as speed approaches the speed of light),and the difference between Special Relativity and General Relativity. Each chapter contains a manga section with an introduction to and discussion of the topic. This is followed in each chapter by a more detailed and technical section filled with equations and deeper explorations of the chapter’s subject.

I’ve studied physics, and although I am rusty, I believe the book is accurate and it is quite clear. The story created to assist with that presentation is kind of silly, but does fulfill its mission of making a difficult topic a bit more approachable and the science communicated in both the manga and the technical sections is clear and well expressed.

My kids are too young to really understand all of the details of the topics covered in this series, but they continue to read the books with great interest. Most of the science is above the grade level even of my oldest (age 9), but their attention remains fixed on the art and the story and the kids are absorbing some of it as they read.

Overall, I would say the book is a success and recommend it without reservation for anyone wanting an accessible introduction to Einstein’s Theory of Relativity and how it changed our understanding of physics.
Disclosure: I was given my copy of this book by the publisher as a review copy.

I like to write. I write for a living. However, working with words to craft sentences is not all I do. My job title is “Senior Technical Documentation Specialist.” Documentation includes more than verbal descriptions. Sometimes, I need to create the perfect diagram.

My job provides me with a MacBook Pro and software. While I often use Dia for diagramming on Linux, at work I use OmniGraffle Pro. Both are quality programs for creating diagrams quickly and easily with good results. They are both similar to Microsoft’s Visio.

I recently had the privilege of reading OmniGraffle 5: Diagramming Essentials by Ruben Olsen.

This may be the strongest title I have read from Packt Publishing. In the past, I have been quite hard on them for poor editing and weak expression of ideas. This is not the case here. The book is well written, clear, and filled with useful information.

I sat down over the last week and worked through all of the book’s examples after reading through the text. I learned a number of  new tricks and shortcuts that will make using the program easier and more enjoyable.

The book begins with an introductory chapter that helps ease the novice into using OmniGraffle for the first time. The chapter includes an extended, step-by-step walkthrough to help the new user create her first diagram. It ends with a set of guidelines that everyone should learn for creating quality visual diagrams. This chapter is the base on which the rest of the book is built. The author leads the reader through stencils and templates, including how to import and use those built for Visio. Then he directs attention to shapes, tools, editing, and making diagrams look good. The book contained no filler or fluff, every page was useful and clear.

If you use OmniGraffle and want a written resource to help you learn it better or for the first time, this book is worth a closer look.

Disclosures: I was given my copy of this book free by Packt Publishing as a review copy.

It has been a while since I have reviewed a manga book. This is one of several atypical educational books that use graphic art to help teach difficult concepts or illustrate the action. This is another wonderful entry in the “Manga Guide to…” series that I have been reviewing.

The Manga Guide to Molecular Biology follows the actions of a two students who failed their molecular biology class and have to take a special summer course. The story line is enjoyable and eases the reader’s entry into the topic rather than being a distraction.

The book covers all the main questions and topics you would expect: what is a cell, what are the common parts of a cell, how do cells combine to make various organisms, what are proteins and how do they function within a cell, what is DNA and what are genes and how do they work to express the information coded in them? My favorite part was chapter 5 which focuses on potential applications for everything discussed earlier and theorizes what the future may hold in the field.

I work in a software project that is helping biologists do research, including helping process the vast amounts of data that comes from genetic sequencing. As a result, I have become familiar with most of the content this book presents. I believe the book is accurate and it is clear. The story created to assist with that presentation is enjoyable as well. I have a seven year old daughter that is reading the book with great interest. Some of the science is above her grade level, but her attention remains fixed on the art and the story and she is absorbing some of it as she reads.

Overall, I would say the book is a success and recommend it without reservation.

Disclosure: I was given my copy of this book by the publisher as a review copy.

I started using Nginx as my primary web server a little over 18 months ago. At the time, I was using an underpowered server with low memory, and I wanted to replace Apache with something lighter. Even though I still love Apache for its power, configurability, and contributions to the open source world, there are times when other options are called for.

Nginx is an http server written in Russia intended for high traffic websites with a mind toward network scalability. It also works great as a lightweight replacement for Apache on my little server with 256MB RAM and one processor (that has since been upgraded, but I didn’t switch back). Even the day I had a post on the front page of of a popular social networking website, my little server withstood the onslaught without crashing.

The hard part of making the switch was finding documentation. As Nginx was birthed in Russia, I presume good documentation may be found in Russian, but since I don’t know the language that doesn’t help me. Finding documentation in English was a chore. Simple things were available at the main Nginx website and wiki (which have also grown and improved over time), but I had a difficult time finding detailed information about specific things I needed, such as translating Apache 301 rewrite rules into a format that would work in Nginx so that I could continue to use WordPress with pretty URLs.

Nginx HTTP Server is the first English book I have seen that compiles quality documentation and instruction for using Nginx. The information is current, detailed, and clear.

Some of the topics in the book seem to me to be a bit odd. There is a whole chapter dedicated to basic Linux shell commands and administration. Perhaps this will be useful for some, but I would imagine most people interested in Nginx will already know the topic. The second chapter discusses downloading source code, configuring, and installing the traditional way along with writing up a SysV init script for the service. I think that is good information to include. Strangely missing is information about installing Nginx from Linux distribution repositories, which is far easier, especially for the presumed newbies who needed the first chapter on shell commands.

The real value of this book is in chapters 3 – 8. Here we dive deep into configuration options, file syntax, modules, variables  and more. We learn how to set up PHP and Python with Nginx, which will make hosting most popular website software like WordPress, vBulletin, or anything built with Django fairly simple. Also discussed are similar methods of enabling other languages and platforms like Perl or Ruby on Rails.

The last two chapters are great for people coming over from Apache. One discusses how to use Nginx as a front end proxy to speed up a website running Apache. The other discusses how to make a full switch. Both include great comparisons and honest discussions of the strengths and differences between Apache and Nginx, including some good advice about when one may be a better choice than the other.

I have a lot of good things to say about this book, and I’m glad it exists. It will remain on my shelf as a useful reference for specific modules and configuration details that are not committed to memory. Comparing its contents to what I already know of Nginx, I believe the book to be technically accurate and current.

The book does have one glaring weakness, though. The quality of the writing is inconsistent. Most of the time, the text is adequately clear and communicates well. However, there is an annoying tendency throughout the book toward awkward grammar and odd phrasing, perhaps as often as one occurrence every two or three pages. This tells me two things: the book was probably written by someone who is not a native English speaker, which is not a big deal at all, and that the copy editing and proofreading was weak, which is a major failing. The initial cringe-worthy portion occurs in the very first paragraph of the Preface:

…for the past few month the same reports reveal the rise of a new competitor: Nginx, a lightweight HTTP server originating from Russia–pronounced “engine X”. There have been many interrogations surrounding the pronounced newborn. Why has the blogosphere become so effervescent about it?

Packt Publishing generally releases books on technology that are current and contain accurate information. The company focuses their efforts on very narrow, niche topics that they alone offer, and I like that. They also have a disappointing habit of being filled with this sort of writing. This book is no exception. Since, like many of their offerings, this is the only book on a topic that is interesting and useful to a specific group of people, I can’t help but recommend that people using or wanting to use Nginx take a look at the book. Still, I would love to see the language of their books rise to the level of their technical content. This would allow me a clearer conscience in recommending their products.
Disclosures: I was given my copy of Nginx HTTP Server free by Packt Publishing as a review copy. I am also a professional writer for a software project and have written for magazines, websites, and books for both O’Reilly Media and Pearson Education (both Prentice-Hall and Sams).

Not long ago I had the privilege of interviewing the authors of what I consider to be the best book for learning systems administration with Unix or Linux from a large, enterprise perspective.  This book is unusual in another way: it was published by Prentice-Hall and the forward was written by one of their competitors, Tim O’Reilly, the founder and head of O’Reilly Media. That says something.

My interview with the authors appeared today on InformIT’s website. Take a look.