Review: Microsoft Manual of Style, Fourth Edition

Author: Editors and Content Managers at Microsoft Corporation
Format: Paperback, 464 pages
Publisher: Microsoft Press; 4 edition (January 27, 2012)
ISBN-10: 0735648719
ISBN-13: 978-0735648715

I don't write technical content for Microsoft products very much these days (read: "practically never") but the Microsoft Manual of Style is not only considered required reading for those folks who do, but even for those of us who don't. Let me explain.

In many companies that produce technical documentation, there is a distinct set of rules that govern the voice, style, and other aspects in how the documentation is to be presented. Most people who aren't technical writers assume I just "wing it" whenever I create documentation for a technical product, but this is untrue. The documentation has to speak to a particular audience and for a variety of reasons, not the least of which is consistency, documentation for technical products must be presented in an exquisitely specific manner. Any technical style guide is designed to provide the writer with a template around which that presentation is organized.

Microsoft's fourth edition of their style guide is constructed into two broad areas: General Topics and Usage Dictionary. The first part is the narrative that addresses general subjects such as web content, the user interface, and even grammar and punctuation. The second part is the dictionary, but one that offers correct spelling and syntax around technical terms, from beep and bitmask to undo and update. Like any dictionary, you use it when you need to be sure you are using a technical term correctly or if you haven't the faintest idea on it's proper usage (and not all writers know how to spell all words, which is why we have dictionaries).

The first part of the book exists to familiarize the writer with the various aspects of writing style expected when documenting Microsoft products. It stands to reason that Microsoft's internal writing staff all use this book as the Bible; a Bible they themselves have produced. However, plenty of other companies must refer to Microsoft products in their documentation and it makes a great deal of sense to comply with Microsoft's preferred standards when doing so (just as we'd all wish Microsoft would write a version of Internet Explorer that complied with accepted web standards, but I digress).

As the front matter states though, no style guide can contain references to each and every aspect of each and every product, so there will be gaps. Several other references are suggested, both web resources and other guides and dictionaries. Together, this should provide the technical writer with a sufficient set of tools in order to create documentation that is readable by a general audience, internally consistent, and consistent with documents produced by other writers and agencies that comply with Microsoft writing standards.

This isn't a bad way to produce documentation for technical products that have nothing to do with Microsoft, either. Many technical writers work under temporary contract and provide writing services to a variety of companies needing documentation for general customers (such as end users) as well as technical consumers (such as IT staff). Smaller companies especially, won't have their own preferred style guide for their documentation, so it will be up to the writer to consult with the ops or dev team supervisor to agree upon a preferred style. While the Chicago Manual of Style is the accepted standard for professional writing, it is not designed specifically for technical documentation. In lieu of any other technical style, Microsoft's style guide is considered the de facto style by most businesses that need technical documentation.

I took a look at the Punctuation chapter in order to sample this book's wares, and was pleased that Microsoft indicated correct vs. incorrect styling as "Microsoft style" vs. "Not Microsoft style." There's more than one way to be right or wrong, but we're talking about Microsoft technical writing style, not general language usage, so what might be "right" in an email, could still be "Not Microsoft style".

You'll never memorize this book, so don't even try. If you are an aspiring technical writer, you don't want this stuck in your memory, anyway. That's why it's a reference and not undying prose. Plus, styles change over time, so you will need to continually adapt in order to stay current. That's also why you will need the current edition, rather than relying on previously published versions.

If you're worried about this guide stifling creativity, then you're in the wrong business. While there is certainly aspects of technical writing that require creativity, there is also a large amount of standards compliance required (and you thought programmers had all the fun). If you document Microsoft products or any other technical asset, assuming you want to write by some objective standard, a very good place to start is with the Microsoft Manual of Style.

A Book Review of The Linux Command Line: A Complete Introduction

Author: William E. Shotts Jr.
Format: Paperback, 480 pages
Publisher: No Starch Press; 1st edition (January 14, 2012)
ISBN-10: 1593273894
ISBN-13: 978-1593273897

Linux has been struggling to become a "desktop darling" of the home and small office user for years and has yet to succeed. I don't know if it will ever succeed. One of the biggest hurdles Linux has to cross is its reputation as being command-line driven. Most people fear the command line and if you're old enough, you remember (with dread) the arcane DOS interface or struggling to remember what command syntax to use with the now ancient Apple IIe. Users love Windows because the GUI is easy.

Ubuntu, of all the Linux distros, is about the best in terms of a user-friendly GUI, and yet even when Windows users abandon the Microsoft "mothership", they almost always turn to a Mac and not to Ubuntu (or any other flavor of Linux). Face it. Linux may never succeed as a desktop operating system and may have to "settle" for being the king of the server and embedded device markets.

But is that such a bad thing?

Ironically, the power of a Windows machine is on the command-line, but unless you're a system admin or network guru, that doesn't even occur to you. And absolutely, the power of Linux is in the command-line shell. Why fight the nature of what Linux is? Instead of trying to avoid shell commands, embrace them. That's where The Linux Command Line: A Complete Introduction comes in.

The hardcopy of this book should be on its way to me for my review right now, but I couldn't wait. The publisher kindly allowed me to also download a PDF version of the Shotts book, so here I am, tearing into it (metaphorically speaking) and getting ready to devour its contents. What secrets does it hold and for whom shall they be revealed?

Scrolling through the beginning of the PDF, I discovered the "Who Should Read This Book" section. According to the author, this book is for the rank beginner in the Linux world who is likely a Windows "power user" and who, for whatever reason, must learn Linux management skills. That's a rather amazing statement since, having scanned the table of contents on my way down to page 29, I discovered a rather impressive list of skills to be learned. Among them were "A Gentile Introduction to Vi" (my favorite editor), "Package Management", "Regular Expressions", "Compiling Programs", and "Writing Shell Scripts". Any one of these topics is worthy if its own book (and they're out there) and certainly they will be intimidating to the Linux novice.

But first things first.

The end of the introduction to the book gives rather brief instructions for how to install Linux on a computer or how to use a live CD, so the reader is presumed not to even use Linux on a regular basis (or at all). On the other hand, there are no links or instructions as to where to find a Linux ISO file for download or how to burn a bootable CD or DVD, so I guess the reader is expected to know something. Oh, in case you're wondering, I'm using Ubuntu 11.04 (Natty Narwhal) to write this review and practicing commands in the default bash shell.

The first section of the book is called "Learning the Shell", which is pretty basic. The first chapter, "What is the Shell" offers the reader a little bit of a history lesson on the shell and how to use very basic commands, such as "date", "cal", and "df". It's a very short chapter and fortunately gets the reader into opening and using the shell right away. It's a gentle beginning. When does the book get "rough?"

Technically, the hardcopy of the book is only 480 pages long, so it's not an encyclopaedia (remember them?). Yet, for not being a massive tome, the Shotts book probably best works not only as a linear tutorial but as a reference. After all, even veteran shell users don't remember everything and I've seen Linux developers with decades of experience still have to look up commands they don't use very often (although they almost always do so using Google rather than grabbing a handy book).

I called this book "a linear tutorial" because the first section is written in just that manner. One skill set builds on the previous ones presented and the more the reader goes through and practices what they're reading, the better they should get at navigating the directory tree, copying and moving files, locating files, and using man pages.

Although there are no exercises or labs at the end of each chapter, there are notes encouraging the reader to pause and to practice what they've learned as well as experimenting and adapting on commands they've been using. The reader is also encouraged to refer back to the help and man documentation on commands, which is a further exercise in using the shell, since these tools are the first ones a system admin or programmer turn to when they're trying to recall that rarely used command switch.

Actually, the book doesn't really need a separate section for exercises since each page in the chapters directs the reader to try out various commands. This is a book that needs to be opened alongside a Linux machine where the reader is simultaneously working in the shell.

It would take too long to review the content in each chapter and section, but there are a few notable mentions. In Chapter 12 "A Gentile Introduction to Vi", the reader is treated to a Vi primer (sorry, Emacs users). It's probably just about as much as a new user will need to edit files on a Linux machine and if need be, books such as Learning the vi and Vim Editors by Robbins, Hannah, and Lamb are always available.

I did wonder about introducing the reader to Regular Expressions in Chapter 19. For the average computer user, even the average Linux computer user, Regular Expressions can be a real "migraine maker". This may be your first clue that not everyone who will use this book will use all of it, at least not right away. Although this is a great skill to acquire, not everyone may be up to the challenge. When reading this book, assess whether or not you want or need to learn everything it has to offer.

Chapter 23: "Compiling Programs" is another chapter that may not always be useful to all readers. The content goes quickly from "What is Compiling" to downloading source code from the web (specifically ftp.gnu.org), examining the source tree, and building a program. Note that the reader isn't expected to know how to actually write a program, so the general purpose of this chapter is to introduce the power of compiling in the shell and, like vi and Regular Expressions skills, is something that can be built upon using other resources if the reader so desires.

All of the fourth and last section of the book is devoted to "Writing Shell Scripts". If the hypothetical reader of this book is someone who wants or needs to learn Linux server management skills, everything presented in the book up to this point is not only useful, but required. Certainly writing shell scripts (and again, there are entire books available on this subject), is a necessary skill set for the Linux systems admin or even for people who just like to "get under the hood" a little.

After a brief introduction, the reader is lead through the "rudimentaries" of their first shell script which is about as basic as echo 'Hello World!' The reader must dig back into what they've learned before about using vi or vim, creating a file in the desired directory, making it executable, and saving it (none of these instructions are presented again in the shell script chapter). The last bit in the chapter gives the reader a tip on how to configure vim for shell scripting by turning on syntax highlighting, highlighting search results, and using auto indent. The rest of the section takes the reader through building a scripting project and pulls together previously learned skills to develop more complex scripts, including teaching the use of loops and arrays.

The final note in the final chapter addresses the reader, "Well, we have completed our journey. The only thing left to do now is practice, practice, practice. Even though we've covered a lot of ground in our trek, we barely scratched the surface as far as the command line goes."

I can agree with that. There's a reason why the book's subtitle is "A Complete Introduction." That's not a contradiction in terms, it's the literal truth. Part of the power of the shell is in its almost infinite potential, which most shell users never master, but if you buy and then use The Linux Command Line: A Complete Introduction to its fullest extent, your "introduction" to the shell will be very impressive.

Review: Kindle Fire Web Experience

I've already reviewed the video and book reading capacities of my Kindle Fire. Time to turn to the web experience. How is it?

One of the things I was looking forward to when I got my Kindle Fire was being able to wirelessly surf the web while not being tied down to a desktop or laptop computer. I expected the experience to be somewhat slower but wasn't prepared for how much longer it seemed to take for a webpage to download into Kindle's Silk web browser. Not quite as bad as dial-up, but I wasn't used to waiting for (by today's standards) ages for a webpage to appear.

To get to a webpage, you can select Web in the overhead menu or select amazon, IMDb, or Facebook from the shortcuts at the bottom of the main page. Selecting Web opens the last webpage you visited, which in my case was marvel.com. I admit that one of the ideas I had was to be able to read comicbooks digitally using my Kindle Fire. I figured buying an annual subscription at Marvel would let me read all of the old comicbooks I loved as a kid but not take up any valuable storage space in the home (or costing me billions of dollars to replace everything I had when I was young).

But first, the general web experience.

To go to another site by typing in the URL, tap the URL bar to make the keyboard appear. Depending on your relative "texting" skills (mine are awful), you can type in the address of the site you want to visit. There's even a .com button so you are spared entering the suffix as individual characters. As you type, the history shows the URLs you've most recently visited, and you can select any of those if it's where you want to go.

While my fingers aren't overly fat, if there are a lot of links or buttons on the page I want to press, I tend to tap and miss the mark. Changing the orientation of the screen from portrait to landscape helps a bit, but of course, I sacrifice the length of the page. When I do "fat finger" the wrong link or button. I have to hit the back button, wait for the previous page to load, and then try again. I don't know if this is a problem in Silk, the website in question not being well designed for mobile web devices, or me being clumsy. It's just my experience. I do find that using a very gentle tap seems to work better in these delecate cases.

Now on to comicbooks at Marvel.

This one I blame on whoever designed Marvel's website.

I'd love to read 1960s vintage comicbooks. It was the silver age and my childhood and Marvel was just a lot of fun back then. You can read the first few pages of any comic for free, so I thought I'd try my Kindle Fire out by trying to read the beginning of an old Spider-Man comic. Here's what happened.

When the cover of the comic loads into the browser, there are two green arrows (no reference to the comicbook character intended) at the bottom of the screen for forward and back. To advance to page one, I have to successfully tap the right arrow. But nothing happens when I do. Or I get a white screen with an exclamation mark in the middle and have to hit the browser's back button. Unlike a book on Kindle, I can't just use a sliding finger motion to move to the next page.

I tried changing to landscape orientation to see if that helped. After multiple taps, page 1 finally appeared. Changing back to portrait orientation makes the page readable. At this point, I can use my finger to drag the page and move to page 2, but there's an annoying tendency to snap back to page 1 when I remove my finger. Frankly, the entire experience is more frustrating than it's worth. I don't want to have to sit at my desktop to read comics. It's something best done sitting in a living room chair or reading in bed late at night.

I don't know if Kindle Fire could improve this problem or if it's something the folks at Marvel.com have to fix. However, the Silk web browser, though passable, still leaves a lot to be desired. Or maybe mobile web browsing still needs to be perfected. In any case, as of now, browsing the web with my Kindle fire is not the main reason I'll be using the device.

SOPA Blackout

Review: Kindle Fire Book Experience

I like to read. To that end, I own a lot of books. My wife complains about the amount of space all my books consume in our home. Occasionally, this results in my having to clean out the shelves and remove the books I don't think I'll even read again. Trouble is, I think I'll always read them at some point in the future. Instead, I donate them to the local library. But then I get more books.

In the Star Trek original series episode Court Martial (1967), Jim Kirk is facing a general court martial for apparently sending a fellow officer to his death in a non-emergency situation (it's a trick, since the officer faked his own death to implicate Kirk as revenge for a problem that happened between them years before). Kirk's attorney is one Samuel T Cogley (played wonderfully by the late Elisha Cook Jr.) who has his own system of practicing law based on old fashioned, hardcopy books. When Cogley is explaining his system to Kirk, he asks, What's the matter? Don't you like books?" Kirk's reply is, "I like them just fine, but a computer takes less space." That's my theory behind reading on the Kindle Fire.

I'm actually a bit torn. Like Cogley, "I like books". I'm old enough to still think that a "real" book is better than an electronic copy, but I have to balance desire with practicality. The Kindle Fire will never be able to replace the feel or the smell of an old book, but the content and the magic will still be there on each page I swipe (instead of turn). The Kindle Fire has a 6.5 GB storage limit on its hard drive but Amazon offers free unlimited cloud storage for anything purchased at Amazon (you can store non-Amazon products in their cloud free too, but only up to 5 GB...to upgrade to 20 GB of storage for said-files costs $20.00 a year), so "book shelf" space doesn't seem to be a problem.

I was intriqued by Amazon's free lending library for Amazon Prime users. Since I have a month's free trial of Prime, potentially, I have access to thousands of library books which I can borrow from Amazon for free. This sounded fabulous, but there's a catch.

I fired up my Kindle (pun not intended) and on the main page, tapped "Books" and then "Store". On the Books page, there's menu on the right side and I tapped "Kindle Owner' Lending Library". A list of various categories (Fiction, Nonfiction, Comics & Graphic Novels, etc...) appeared. Once I made a selection (Fiction) I saw a list of books, some available through Prime for free, but nothing to indicate that they could be borrowed. I selected one at random and when the book's "details page" appeared, there indeed was a button that said "Borrow for Free". I scrolled down for awhile but didn't find anything that looked appealing (in spite of the number of books I own, I'm actually picky about what I read).

I decided to try "Comics & Graphic Novels" and received a bit of a shock. The "graphic" part has to do with sex. A huge percentage of this collection is virtual porn, with titles such as "Wicked Desires: Steamy Sex Stories Volume 1", "My Sister Bestfriend", and "Sex Messages, Social Networking, and BDSM". The actual comic books were neither DC nor Marvel and seemed to be rather seedy, off-brand tales from the 1950s and 60s. Anything worthwhile (Batman, Green Lantern, Watchmen) cost about $10.00 each. I also noticed DC but no Marvel titles, which was quite a let down.

I did discover one cool thing. Lots and lots of pre-1923 books that are out-of-copyright are available for free..not to borrow, but to own. I immediately downloaded a copy of Robert Louis Stevenson's Treasure Island and burned through the first two chapters. And at the risk of sounding like a TV commercial huckster, that's not all. Amazon also points you, via their website, to numerous library projects that offer over a million free titles. Projects such as archive.org and gutenberg.org, complete with instructions on how to access their content from Kindle Fire. I haven't tried this part out yet, but believe me, I will.

As with movies and TV shows, the number and type of books you can borrow or get for free through Amazon Prime or the Kindle Owner's lending library is limited. The comic book and graphic novel selection was particularly wanting and I was severely disappointed. I really think there needs to be an online archive project specifically for older comic books, since their physical copies won't last forever and the originals held by the publishers are reproduced and distributed at the mercy of those companies. I guess that's my problem, though and I suspect that availability of book and comic book titles is limited by licensing costs. Besides, Amazon and the various publishing houses have to make a buck somehow.

In spite of the roadblocks I encountered, I still discovered that I have access to a large selection of reading material. Not everything I want, but books that I can't find, even at my local lending library. Speaking of which, I can't wait to see how to actually borrow a digital book from my public library for Kindle Fire. In the meantime, I'm going to be happily making my way through Treasure Island. "Yo ho and a bottle of rum, mateys."

Oh, and if you liked this review, make sure to catch my other Kindle Fire review on my experiences with movies and TV shows.