What's your tech writing bible?

June 12, 2008 7:15 PM

What's your tech writing bible?

So I'm writing a tutorial for a bit of software.

When it comes to the WHAT and WHY of it, I'm all set — it's a tool for researchers in my field, so I could go on for hours about the ideas behind it. But the HOW is proving tricky for me. Listing the steps to follow to do X, or describing what button Y does, or explaining how to find Z in the output, just leaves me incoherent.

I'm looking for a good book (or website?) on technical writing that will explain how to write well about this stuff. I'm a writer first and a techie second, if that matters, and I don't mind spending some time reading — I'd prefer something solid and comprehensive to a Fifteen Minute Guide For Dummies. Suggestions?

posted by nebulawindphone to technology (11 comments total)

You can't really go wrong with the Microsoft Manual of Style. The first few chapters of the book discuss the 'how' and should get you up to speed in 60-70 pages.The back of the book is a dictionary-type lookup that you can use for quick reference reference.
posted by mattybonez at 8:10 PM on June 12, 2008 [2 favorites has favorites]

Ditto the MS Manual of Style, or maybe the Chicago Manual of Style.

Better yet, the style guide from the publisher if there is one.

I've found my best resource for tech writing is just to have a few excellent tech books around to refer to. How did THEY do it?

If your tutorial is for a publisher, web site, magazine, etc, I'd read through lots of their other tutorials. Being similar to the style their readers are used to is more important than achieving some sort of stylistic perfection.
posted by mmoncur at 8:36 PM on June 12, 2008

(Alas, there's no publisher and no style guide. I'm a grad student, and the whole team for this project is my advisor and two other students; as long as it gets written, none of them are particular about how the i's are dotted and the t's are crossed. So I really do feel like I need some kind of outside guidance on what makes for good writing.)
posted by nebulawindphone at 9:06 PM on June 12, 2008

The Microsoft style guide (or MSTP as it's called in Redmond) is really quite good. Sun's Read Me First! is also worth having, probably, though I haven't looked at it in a long time and haven't seen the second edition at all.
posted by kindall at 11:00 PM on June 12, 2008

Just tossing this one out there (we don't use a style guide at work, although we should):
O'Reilly Stylesheets and Style Guide

It's focused more on the low-level elements of style, but might be what you're looking for. I've always found the O'Reilly technical publications to be pretty easy to read.
posted by Kadin2048 at 12:19 AM on June 13, 2008 [2 favorites has favorites]

Bugs in writing by Lyn Dupré is worth reading, although I wouldn't make it my only reference.

(For some reason this books seems to really rile some people: especially humourless types who regard any book that has a distinctive 'personal' voice as being beyond the pale. The cats especially seem to set some of them off. Read the one star Amazon review for entertainment if nothing else.)
posted by pharm at 1:08 AM on June 13, 2008

(Although that work may be too general for the original question.)
posted by pharm at 1:09 AM on June 13, 2008

I agree that you should have the Microsoft Manual of Style. The latest version is Version 3. Microsoft had a difficult time getting it published in a timely manner, and so for a while offered it as a free download. It is still available for free download here.
posted by Houstonian at 3:44 AM on June 13, 2008 [2 favorites has favorites]

(Shameless promotion for a free product)

You can download my "Creating Great User Documents" Course totally free here:http://www.greatuserdocs.com/DownloadCourse.htm

The Course guides you in creating a great User Document for any kind of product.
There are absolutely no strings attached, the site doesn't even ask for your name or e-mail address. Take a look.
posted by mbarryf at 5:15 AM on June 13, 2008

I'm glad to see Sun's Read Me First on the list. I think it's slightly more usable than the Microsoft manual, although both are here within hand's reach: stained with coffee, dogeared, and full of Post-It flags.

nebulawindphone, I'm a tech editor by trade. If you want some input or a quick tutorial, feel free to MeFiMail me.
posted by catlet at 6:33 AM on June 13, 2008

The focus isn't on software, but I have learned lots from Michael Alley's "The Craft of Scientific Writing."
posted by fantabulous timewaster at 2:34 PM on June 14, 2008