The Society for Technical Communication is an individual membership organization dedicated to advancing the arts and sciences of technical communication. It is the largest organization of its type in the world. Its 25,000 members include technical writers and editors, content developers, documentation specialists, technical illustrators, instructional designers, academics, information architects, usability and human factors professionals, visual designers, Web designers and developers, and translators - anyone whose work makes technical information available to those who need it.

The STC Toronto Chapter was founded in 1959 (then the Society of Technical Writers) and is the largest chapter in Canada.

About this Newsletter:

A Writer's World:
by Andrew Brooke

Let's start the new year with a tribute to every metrosexual's favourite show, Queer Eye for the Straight Guy.

Clear Eye for the Documentation Guy

Introducing the "Clear Eye for the Documentation Guy" team:

• Carson - Customer Review
• Ted - Information Development
• Jai - Content Management
• Thom - Information Design
• Kyan - Indexing & TOC

* * *

Carson: OK - so who's our first documentation victim?

Ted: His name's Lionel. He's a tech writer from New Jersey, and he works at a place called "Fabulous Systems"

Carson: Oooh - great name. I think I'll call my first-born child that.

Ted: Unfortunately, things aren't so "fabulous" for Lionel - he's been working on a big user guide; it's over 300 pages long. It's for the company's flagship product, "The Web Whacker", which is, according to the company's website, the "premier tool for safely removing spyware and cookies from your system".

Carson: But why would you want to get rid of cookies? Cookies are yummy-licious!

Thom: I guess if you want to retain your girlish figure.

Ted: Anyway, Lionel needs help. The user guide and online help need alot of work. Currently, Lionel's using a separate tool for each.

Jai: Two separate tools? Oh my god!!

Ted: Yeah, his documentation is really hurting. Seems it hasn't been reviewed since the middle ages. There's broken cross-references, outdated screenshots, missing procedures, wrong info, duplicate text...

Carson: Oh stop it! You're killing me alot!!

Thom: We gotta help this poor boy make his docs shiny and new. He needs the "clear eye" treatment right away...

Chorus:

You came into my life
And my docs never looked so bright
It's true, you bring out the best in them
When you are around
When you are around
My docs just keep getting better

The reviews keep getting better
Drafts keep getting better
All the content just keeps getting better...

Carson: OK - here we go! Let's get that boy's docs "straightened" up!

Lionel: Hey, it's the fab doc five! What's up?

Carson: The quality of your documentation, once we're done ravaging it. Let's see your little monster of a user guide...

(Everyone gets a copy of the guide to gawk at.)

Thom: Oh my god - what's that smudge on the cover?

Lionel: Uh, that's our company's logo. The resolution isn't so hot.

Carson: "Isn't so hot"? Honey, it's colder than Martha Stewart at the North Pole.

Jai: What's up with the table of contents? It's 17 pages long!

Carson: I guess he likes a big table. You can seat more guests that way...very festive.

Lionel: Yeah, it is kind of big, I guess. It has all the headings up to heading level 5. I couldn't really figure out how to make it shorter.

Carson: Some things are better longer, trust me.

Jai: Don't listen to him - he's evil. We're gonna make your TOC R-O-C-K!

Thom: Uh, excuse me - why is the word "actualize" in your document?

Lionel: I think that came from marketing.

Jai: I don't think that's really a word, is it?

Carson: It is on one of Jupiter's moons, "Psycho".

Kyan: We need to send that word back to the depths of hell from which it came.

Ted: Uh oh - you've got a cross-reference here that points to a page that doesn't exist.

Carson: Oh, it exists, alright - you just need to wear your special super-duper magic wizard x-ray glasses to see it. Either that or drink lots of champagne and say the magic incantation: "there's no page like home... there's no page like home..."

Thom: Hey, I can't see what's in this screen shot on page 246. The type in it is tiny!

Jai: Maybe your eyes are too big.

Carson: Oy vey - where's an electronic microscope when you need one?

Ted: It's OK - I brought a magnifying glass just for this occasion. Let me take a look. OK - I think can make out the letters - wait a minute - I think it's in hieroglyphics.

Carson: Boy, those ancient Egyptians really knew how to make software, didn't they?

Lionel: I think some of the fonts in the screenshots got "pixilated".

Thom: Those pixies will get you every time.

Carson: We'll just sprinkle some magic anti-pixie dust on the screenshots - that should fix it.

Thom: Uh - you've got a procedure here with 32 steps. Don't you think you should break it up a little?

Carson: Don't you know that breaking up is oh-so-hard to do?

Jai: Hmmm...your index is interesting. You have entries for "edit", "change, "modify" and "update".

Carson: Well, at least he's consistent.

Jai: You've also got some entries in uppercase, some in lowercase and others in mixed case.

Ted: Oooh - I'm not comfortable with "mixed case". We don't want those capital letters fraternizing with those lowercase letters. Who knows where that could lead?

Thom: I wouldn't make a federal "case" out of it.

Carson: But it's definitely a "capital" offense. He's probably all mixed up from having to sort out his multiple personalities.

Thom: Lionel, when was the last time someone actually reviewed this guide?

Lionel: Hmmm..I'm not really sure...

Carson: Maybe all the SMES got sucked up into that 24-hour black hole that's been floating around. You know, the SME-sucker.

Lionel: It's probably been awhile.

Jai: A while? How long is a "while"?

Ted: I think the going exchange rate is two "whiles" to a year.

Carson: Save the "whiles", I always say...you never know when you might need one.

Thom: OK - I think we know what needs to be done. And we're just the guys to do it!

Carson: That's right! It's a group effort! Remember, people, there's no "I" in "technical writing"!

Thom: Let's get to work...

* * *

A long "while" later...

Ted: OK, Lionel. We're done with your documentation makeover. We're going to take you through what we did.

Carson: And be sure to take notes, you bad boy. There's a test later.

Jai: A test? Written or oral?

Ted: Don't go there...We'll start with Carson, our Customer Review guy...

Carson: Well children, as we all know, the first step in any makeover is to look at what you've got, then work the problem. Like I always say: "if you're not part of the solution, you're part of the equation."

Thom: Uh, Carson, shouldn't that last part be "you're part of the problem"?

Carson: No, you're part of the problem!

Anyway, I took out a bunch of your customers for some lovely Japanese tea, and I picked their cute little brains about the documentation. I'd tell you what they said, but I'd be breaking about 14 FCC obscenity regulations. Let's just say there's definitely been a major "documentation malfunction".

The gist of it is, the users weren't very happy campers. They couldn't find what they were looking for, the index was like a bad hair day, tons of your procedures didn't have any of those darling "big picture" overviews, and half your users of them are now legally blind from trying to read your Egyptian screenshots.

Lionel, your user guide and online help were really "criminal", but the fab doc five have joined forces to expunge your record, so you no longer have to live in fear in the technical writing witness protection program.

Ted, our Information Developer, will be the first one up to tell you how we healed your very sick docs...He is truly the Doc Doctor.

Ted: The big problem was that you had the manual organized by product modules, rather than by task. So we restructured things to be more task-oriented. This includes always having an action verb in your headings.

Thom: Ooh - where I can get some action?

Ted: So, for example, instead of headings like "Cookies" and "Pop-Up Ads", we now have "Deleting Cookies from Your System" and "Getting Rid of Pop-Up Ads".

Another big problem was that many of the procedures were out of date, inaccurate or just plain missing. We sat down with the developers and went through every screen, field and process in the application, and cross-checked it against the document. We found some real information "jewels" that were missing.

Carson: Gotta take care of those family jewels, people!

Ted: We talked to your very friendly QA and support gangs and asked what were the most common problems and the best way to fix them, and then we stuck that info in the guide. That should help your support people, who I think were on the verge of a nervous breakdown.

We updated all your screen shots, fixed all the broken cross-references, broke up procedures that were too long, added a bunch of missing overviews, and, as a special treat, we added another chapter - if you turn to page 426...

Thom: Wow - a Glossary of Terms!

Carson: Hey, let's look up the meaning of life.

Ted: We also got rid of a lot of your duplicate text. I'm going to turn it over to Jai, our Content Management God, to talk about that.

Jai: For some wacky reason, you were using one tool to develop the Online Help and another for PDF file, with practically the same content in both. That's a big no-no.

Carson: It's actually a no-no-no-no-NO!

Jai: We went through and merged all the text together into one document, which you can output as a PDF or a Help project - whatever your little heart desires. This should cut your workload in half.

Carson: This means you only have to work 2 1/2 days a week. Your boss will be ecstatic!

Jai: We also noticed you had two different product versions: a regular edition and a professional edition. In your guide, you had stuff like "If you are using the regular edition...". or "If you are using the professional edition" with almost the same procedures in each part. That's another no-no.

Carson: I think we're up to about 6 no's, no?

Jai: We merged the duplicate procedures and used conditional text for each version. Now, the regular users will only see the stuff that applies to them; same goes for the "pro" users.

Carson: "Regular"..."Pro"...can't we all just get along?

Jai: Up to this point, we've only been talking about the content. Thom, our Information Designer, is going to give you lowdown of the "look and feel".

Carson: I wouldn't mind doing a little "looking and feeling" myself...

Thom: OK. Basically, your choice of fonts was more messed up than Robert Downey Jr.

Ted: Hey, don't make fun of Robert - he's misunderstood!

Thom: You used three different fonts in your headings and the point sizes ranged from 10 to 30.

Jai: Oh my god! Lionel - what colour is the sky in your world?!

Thom: We fixed things so that your Heading 1 is now a very respectable 16 points, followed by 14 points and 12 points for Headings 2 and 3. And all your headings now use the same font.

In your online help, you were using serif fonts, which are harder to read on-screen than sans serif fonts like Arial.

Carson: Serif fonts on screen?! Gag me with a CD-ROM!

Thom: All your help fonts are now sans serif. The help files have a clean and simple look, with three tabs: Contents, Index and Search. We've also got your standard government-issued help buttons for navigating, bookmarking, printing...

Carson:...eating, drinking, shopping, bitching...you get the idea...

Ted: It should all look very nice with your furniture.

Thom: In the long run, we're recommending that you get a content management system. You've got lots of stuff that repeats throughout all your documents. A content management system, or "CMS", will get rid of the duplication, and help you build and maintain documents much more easily.

Carson: So you need to get an XML CMS ASAP, and you'll be a VIP and maybe the next VP, or else you'll be MIA.

Jai: Let's not push the boy too hard. I think he's still in shock from what we've done so far.

Carson: But we're the "shock and awe" gang. I love that phrase - "shock and awe". Reminds me of "Chaka Khan", that cute little one-hit wonder.

Ted: Kyan is going to wrap things up by explaining how we handled the front end and back end of your docs - your TOC and index.

Kyan: As we talked about earlier, your TOC, at 17 pages, was a "tad" unwieldy. People need a TOC they can quickly scan. It shouldn't try to be an index.

Carson: Yeah - that's like Madonna trying to be an actress. Or a singer...

Kyan: Your TOC now has just the chapter titles and headings 1 and 2. This knocks it down to 5 pages, a much more digestible amount.

Thom: And we all know how important it is to have good digestion.

Kyan: Moving on to your index. Well - what I can I say? It was scarier than the documents that programmers try to write.

Carson: Oooh, that is scary! I'm so scared I want to put on my witch's hat.

Ted: Which witch?

Kyan: Oh stop it!

In your index, you had entries jumping to the wrong location, your case was all over the place, you had a bunch of different words describing the same thing, and many of your topics had no entries.

Thom: Lionel! Kyan! For shame! Shoot zem. Shoot zem both.

Kyan: We went through all your index entries, cleaned them up, took out the dead ones, added a bunch of live ones, and made everything groovily consistent.

Carson: Basically, we made it look like Sybil didn't write it.

Ted: So there you have it, Lionel - we took your user guide from junky to funky! How do you feel?

Lionel: Wow - I'm speechless. You guys are the best. I don't know what to say. You saved my life!

Carson: Oh stop it, I'm getting all teary-eyed.

Thom: Someone throw that man a hanky.

Ted: Wow - yet another document restored to sanity. We did good, fellahs!

Jai: This should really impress his boss - he'll probably get a promotion.

Carson: Yup - he could be the next CFB: Chief Font Boy.

Kyan: Sounds good. A toast - to Lionel - may his writing never falter, may his screenshots be sharp and pure, and may his hard drive never fail.

Carson: And may he always remember our motto:

Carson, Ted, Jai, Thom and Kyan (in unison): We're here, we're clear, get used to it!

Andrew Brooke (abrooke@insystems.com) is a Senior Technical Writer at InSystems and blogs regularly.