Comments on: What's your tech writing bible?

Question: What's your tech writing bible?

nebulawindphone — Thu, 12 Jun 2008 19:15:39 -0800

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?

By: mattybonez

mattybonez — Thu, 12 Jun 2008 20:10:18 -0800

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.

By: mmoncur

mmoncur — Thu, 12 Jun 2008 20:36:53 -0800

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.

By: nebulawindphone

nebulawindphone — Thu, 12 Jun 2008 21:06:46 -0800

(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.)

By: kindall

kindall — Thu, 12 Jun 2008 23:00:58 -0800

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.

By: Kadin2048

Kadin2048 — Fri, 13 Jun 2008 00:19:53 -0800

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.

By: pharm

pharm — Fri, 13 Jun 2008 01:08:38 -0800

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.)

By: pharm

pharm — Fri, 13 Jun 2008 01:09:38 -0800

(Although that work may be too general for the original question.)

By: Houstonian

Houstonian — Fri, 13 Jun 2008 03:44:58 -0800

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.

By: mbarryf

mbarryf — Fri, 13 Jun 2008 05:15:25 -0800

(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.

By: catlet

catlet — Fri, 13 Jun 2008 06:33:42 -0800

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.

By: fantabulous timewaster

fantabulous timewaster — Sat, 14 Jun 2008 14:34:08 -0800

The focus isn't on software, but I have learned lots from Michael Alley's "The Craft of Scientific Writing."