Words and Software : Technical writing

Writing good technical documentation, part 3

Jeanie Decker — Wed, 22 Jul 2009 07:45:00 GMT

Nathan Bransford, a literary agent, blogged about his difficulty in getting writers to paste their original query into their partial manuscript. Here are the instructions he sends them:

"Thank you for your recent note. Would you mind sending me the first 30 pages in a Word attachment? Please paste your below e-mail in the first page of the Word document. I look forward to getting to know your work."

He estimates that he has about a 75% success rate (not bad!) but would like to improve it. Enthusiastic commenters offer numerous suggestions for rewording the instructions, and at least one of them mentions that it's like technical writing, which of course caught my attention.

Technical writing is full of procedures (or instructions, if you prefer that term). From my perspective working on server products here at Microsoft, the main purpose for the documentation is to help you do something with our product, and quite often the means is a "how to" procedure.

How can you go wrong with procedures? Well, the obvious answers are missing steps, having the wrong steps, using jargon that doesn't match what the user sees, and so forth. But a procedure can be methodical and precise and accurate, yet still not meet the user's need, if it's missing the "why".

I'll use one of my own topics (where I failed on "why") as an example:

Vendors might periodically update a management pack. When a management pack is updated, the version number incrementally increases. You can check the version number of imported management packs in Operations Manager 2007.
To check the version of a management pack...(procedure follows)

Version number can change, you can check it -- but why do you care whether the version number changed or not? What good is that knowledge to you? I haven't given you any idea when you would want to check it or how you should know to check it or what to do with the version number once you have checked it. All of that belongs in "why". (Meanwhile, I've sent myself a note to update that topic.)

Awhile back, in one of those team-building type workshops companies love, we did an exercise where one person had all of the instructions and the other team members had pieces of information. The "leader" had a goal to accomplish that required coordinating all of those pieces of information. Our team was the first to finish, but every member stated that it would have been a lot easier if they had been told what the goal was and why they were doing certain things. (That stuck with me all this time because I was the person who had the goal and failed to share the "why" with the team.)

An adequate procedure tells you "how to". A good procedure tells you "when" and "why" and "then what". Which brings me back to Nathan's post. When I read it, my first thought was that he should tell the writers that he reads their submissions in his Kindle and that is why he needs the query in the partial -- if I understand the why, I'm more inclined to cooperate. Since several commenters made the same suggestion, I refrained from adding to the thread there and hijacked the thought into a post here instead.

Writing good technical documentation, part 2

Jeanie Decker — Tue, 10 Mar 2009 06:54:00 GMT

(Part 1)

Joel Spolsky has an excellent post on the role of the program manager. I work with program managers, so I read through it comparing his descriptions with the PMs I've known. Then I got to the part on functional specifications and my interest level jumped a few notches.

Because the spec is -- or can be -- one of the technical writer's best tools.

By coincidence, my manager recently asked us to jot down what we considered to be characteristics of a good spec for a software feature (from a writer's POV). My contribution:

What it is
Why it is
What it does
How it works
When it does it/is used
Who uses it

That's not too much to ask for, is it?

If you're the writer and you're not involved in your team's spec reviews, ask to be included. Read the specs, ask questions, make suggestions. Remember, whatever they develop from it, you'll have to explain to the customer.

(As a side note, that brings to mind one quality that a good tech writer must have -- the willingness to ask "dumb" questions. If you don't ask the question because you're worried that it might make you look silly, you're doing yourself, the customer, and the team a disservice.)

Back to specs. The spec sets the stage for the story that your documentation will tell. From the specs, you should be able to start crafting the high-level design for the docs: what the user will be doing and what they need to know to do those things, what method and organization for the documentation will be most useful for that type of information.

If the specs you work with don't include user interface mock-ups, finagle your way into those UI meetings and reviews as well. Look at each screen with the question "how am I going to explain this?" Be the customer's advocate: "Why am I clicking Next three times?"

Writing good technical documentation, part 1

Jeanie Decker — Wed, 07 Jan 2009 09:40:00 GMT

A recent comment by "BPM software" suggested that I write about best practices for writing technical documentation. I thought about it for awhile and decided I couldn't really do it justice in one post - hence, "part 1".

I'll begin by plagiarizing myself. What I said about management packs is just as true in this context:

Ideally, good technical documentation tells you everything you want to know and doesn’t tell you anything that you don’t want to know.

The key in that statement is you. Whether the content is good, whether it answers your questions, whether it avoids wasting your time with irrelevencies...all of those are defined by you, the reader.

Just about every book/class/seminar/workshop on communicating effectively starts at the same place: know your audience. Why? Because I have to know who you are so I can figure out what you'll want to know and what you don't want to know. It's really easy when it's 1:1, like when I write up instructions for a relative.

There are just too many readers in the professional world, though. So technical documentation tends to become "everything anyone might want to know" because we usually prefer to offer at least some value to many rather than great value to just a few.

So, the first best practice is to define your reader (customer, user) as best as you can. To document software, I consider the two main questions to be:

What does your reader want to do?
What does your reader already know?

To answer the first question, you need to learn about the problem your reader has that he wants to solve, about the environment he'll be in, and about his expectations for a solution. All of this information helps you define what the reader wants to know and, in combination with the answer to the second question, helps you define what he doesn't want to know.

Your answers to the questions may also reveal that you have more than one type of reader. Take Operations Manager, for example. We have customers who want an efficient method to monitor many servers. We also have customers who want an easy way to create their own custom monitoring solutions. Some of those customers are support technicians who want documentation that will help them monitor and some of those customers are developer-types who want documentation that will help them create customized solutions. So right there we have two very different readers who need distinctly different documentation.

When your readers have different goals and different levels of knowledge and experience, don't try to write to all of them in one document (if you can avoid it).

I'll be honest, we're not fully there yet with Ops Mgr. Some of our documentation tends to skirt between those two readers. We recognize that we've muddied the waters a bit, which serves neither reader very well, and we're working on repairing that problem in future versions.

How not to write a user manual

Jeanie Decker — Tue, 22 Apr 2008 05:52:00 GMT

I have to disagree with Tony Soper's admiration for the Pong user instructions:

"Insert quarter

Ball will automatically serve

Avoid missing ball for high score"

Tony and I worked together on the same team, so he's used to my contrariness. :-) I don't object to calling Pong's instructions "succinct", but I just don't think they're useful.

The key to manuals and instructions is who you are writing for. If you know how to play Pong, you don't need those instructions, so the instructions must be intended for someone who has never played it. But if you've never played Pong, you still don't know how. "Avoid missing ball" gives me no idea how to manage that feat.

Less is not always more.

Web vs. print challenges

Jeanie Decker — Fri, 07 Sep 2007 20:12:00 GMT

If you took a look at the DPM 2007 Operations Guide during the beta, you might have noticed that the server chapters have a similar organization:

general maintenance
management
data recovery

And within those sections are parallel topics, such as:

renaming the server
applying OS updates
using Windows maintenance tools

A few times I've questioned whether it would be better to promote the topics and demote the server types:

Server prominent	Topic prominent
Exchange Servers General maintenance Using Windows maintenance tools	General maintenance Using Windows maintenance tools Exchange Servers

I go back and forth on the final organization. But based on conversations with customers, I decided to go with the server-centric organization - thus, a DPM admin who is working with protection of SharePoint servers can find all of the operations content in a single SharePoint section, even if some of that content is the same as in the SQL section or the file server section.

But what I'm considering doing is adding a new section that promotes the topic, as in the table above, so "Exchange & Windows maintenance tools" has two homes. If you're browsing the TechCenter navigation tree, looking for guidance on using chkdsk on a protected Exchange server, you could then find it by going in through the Maintenance node or by going in through the Exchange node.

If I do that and you download the final Operations Guide as a file, it would contain an awful lot of redundancies. But if I optimize for file format, that's really not effective for the discoverability and navigation challenges of the web presentation. So I figured if I wrote it up for this blog, I'd reach a final decision by the time I got to this point.

I'm thinking about it...

It's worth your during

Jeanie Decker — Sun, 25 Mar 2007 00:10:00 GMT

I know, you're tired of hearing about difficulties translating the american-english language. Still, when I encounter such an amusing example, I just have to share...

They didn’t care about my schedule, offering only general remarks about making it “worth my during.” I think they meant “while.”

From Alison Bowman's The Copywriter, via the Slush God.

Task-based documentation

Jeanie Decker — Sat, 24 Mar 2007 21:52:00 GMT

I'm packing up for the WritersUA Conference with great anticipation. It's a bit of a busman's holiday for me. Lately I've been immersed in the technical aspects of what I was writing about, so it's a pleasure to step back from that and think about the art of user assistance in general.

If you didn't know, one of the key mantras in user assistance is task-based. One of those well-meaning phrases that seems to become fuzzier the more it's repeated. The literal-minded translate it to "the steps of the task", and I can tell when I'm looking something up in documentation if it was written by someone from that camp -- I'm told what to do, but given little or no information about why I would want to do it or what my other options are or how to make the decisions inherent in the steps.

I think I've found that to be the greatest disconnect in documentation for me, as a user. Instructions are plentiful...but too often they assume you already know what you want to do (i.e., the specific tasks that accomplish your ultimate objective).

Good article on the topic: "Help Is Dead. Long Live Help!"

Those pesky computer innards

Jeanie Decker — Wed, 14 Feb 2007 19:42:00 GMT

This was a headline this morning on msnbc.com: IBM says it has doubled speed of computer innards.

Of course that got my attention -- did IBM really say "innards"?

No innards in the story. "IBM has devised a way to triple the amount of memory stored on computer chips and double the performance of data-hungry processors..." Faster memory and processing is great, but I was really more intrigued by the idea of faster innards.

As in journalism, it's often a temptation in technical writing to slip into the casual tone and conversational vocabulary. Unfortunately, casual and conversational tend to make things fuzzy just when the reader is counting on precision. A recent example I came across was "Clear the directories and try again." Um, do I delete everything in the directories and leave the directory structure, or delete all of the directories? I guess I'll just delete the innards and see what happens!

Microsoft language, in a cloud

Jeanie Decker — Fri, 12 Jan 2007 08:19:00 GMT

This is only tangentially related to technical writing, but a post by Matthew Stibbe brought to my attention an interesting analysis of Microsoft language over the years. It's an interactive tag cloud, covering 1976 to 2006, on Todd Bishop's Microsoft Blog. I dragged the slider back and forth for awhile, first looking to see what leaped out at me, and then looking for how often "computer" or "Windows" or "Internet" were the big message.

Some of the timepoints are taken from documents on a narrow topic (such as an email from Bill Gates on "Our smartphone strategy - responding to Symbian"), but many are from product launches, keynotes, finanacial analyst meetings, and interviews. In April 2004, "radino" caught my eye. I didn't click through to read who was really being referred to -- I prefer to think they were discussing Blue Oyster Cult. In the same cloud are "silly", "hey", "huh", and "blah".

How to write really bad instructions

Jeanie Decker — Tue, 19 Sep 2006 06:02:00 GMT

This evening, trying to assemble a pressure-mounted baby gate for my dog, I picked up several tips and tricks for writing really bad instructions that I just have to share for everyone's edification:

Only name half of the parts in the diagram. Users enjoy the challenge of matching line drawings with three-dimensional pieces and matching them to the procedure through the process of elimination.
Put the procedure illustrations, the parts diagram, and the assembly instructions on widely separated pages. This will encourage the user to get familiar with the booklet by paging back and forth.
Make assembly a game for the user by showing one method in the illustration and then sneaking in a footnote that tells them never to do it that way with model X (model X being the one they bought).
Slip in a reference to a part that isn't labelled or named anywhere else in the book. Context makes it too easy to guess - users like to be challenged!

How to add RAM to a laptop

Jeanie Decker — Sun, 10 Sep 2006 06:12:00 GMT

Over the years, I think I've replaced just about everything inside my desktops except the motherboard. But I've never even peeked inside my laptop. Somehow I absorbed the edict that only "authorized technicians" could touch one.

I had this extra memory though.

And a great set of instructions. This is an excellent example of good technical writing made great by the generous inclusion of clear photographs.

Bullfighter for writing

Jeanie Decker — Thu, 27 Jul 2006 04:08:00 GMT

Matthew Stibbe's review of the Bullfighter add-on for Word and PowerPoint intrigued me enough to try it. It's a quick and easy install that adds a toolbar to the applications.

I decided to test it against my most recent doc, What's New in Data Protection Manager SP1. (If you're participating in the SP1 beta, you can download it from the Connect website.) I clicked Bull Index on the toolbar and got my results:

"Bull Index: 91
Diagnosis: Congratulations - you rely upon standard words to explain concepts. Most concepts will be clear and understood. Keep clean."

(Bullfighter dinged me for "Knowledge Base", but since I was referring to articles in the Microsoft Knowledge Base, I couldn't very well not use the words.)

The Flesch score wasn't as good, only a 38:

"Diagnosis: Teetering on the edge of unclear. The overall meaning remains discernible, but it becomes possible to lose oneself in corollary thoughts, which may be worth exploration, but which can also detract from the core point of the written article."

Bullfighter's diagnosis there seems to be trying to teach through nonexample!

Next time I'll try it against more complicated documents and see if it's helpful.

Learn from nonexamples

Jeanie Decker — Thu, 20 Jul 2006 19:30:00 GMT

I think that content at Microsoft has gotten better over the years at providing examples. Examples are a good thing. What we still tend to overlook are nonexamples.

Nonexamples can be as effective, or even more effective, for learning. They provide an extra dimension that adds depth to a concept. Granted, they might be rather obvious in some circumstances...

"A protection group member is a data source within a protection group. For example, you add volume D:\ on server FS01 to a protection group, so volume D:\ is a protection group member. You did not add volume F:\ to a protection group, so volume F:\ is not a protection group member."

That concept just didn't need a nonexample to make its point. How scheduled consistency checks work did, and it worked itself neatly into the middle of the example:

"For example, on Sunday, you modify your protection group options to schedule a daily consistency check. From Sunday to Wednesday, data protection jobs are successfully completed and all replicas are successfully synchronized. Even though a daily consistency check is scheduled, it does not run because all replicas are consistent. Then, on Thursday, a large number of new files are copied to a protected file server and the synchronization log on the file server runs out of space. The next regular synchronization fails, DPM generates a "replica is inconsistent" alert, and the affected replicas are marked as inconsistent. Because you have scheduled a consistency check, DPM performs the consistency check at the scheduled time and repairs the replicas."

An example of making a point by using only nonexamples is Some Basic Guidelines on Writing Well at Miss Snark's.

The system tray that never was

Jeanie Decker — Wed, 19 Jul 2006 20:29:00 GMT

In a a recent post, The Old New Thing made reference to terminology errors, citing the system tray as an example.

To quote:

"One of the most common errors is to refer to the Taskbar Notification Area as the "tray" or the "system tray". This has never been correct."

We recently had several vigorous discussions in our groups about various terms that our product would use. What-will-we-call-this-thing is a fun and interesting exercise, but it's not a science. Bottom line is trying to find a term that will work for the users.

If the users fix on terms that aren't "official", like "system tray", it could be that the official term isn't a good one...maybe we should get crazywild and change "Taskbar Notification Area" to "system tray". Nobody would notice because they always called it that.

Vista is trying to compromise by using the official term but gently acknowledging that it isn't popular: "The notification area is on the taskbar and is sometimes referred to as the system tray."

Development, the microscopic view

Jeanie Decker — Tue, 18 Jul 2006 19:18:00 GMT

Whether it's software or content, making a change can often be a much bigger deal than you'd think. I was reading The Best Software Writing I, selected and introduced by Joel Spolsky, and came across a delightful essay on that very topic.

It was from Eric Lippert's blog back in 2003, and fortunately it's available in his archives so I can share it with you without the struggle of "how much quoting is fair use for a review".

For your reading pleasure, "How many Microsoft employees does it take to change a lightbulb?".