Words and Software

Writing good technical documentation, part 3

2009-07-22T07:45:00Z

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.

R2: check for MP updates

2009-06-19T19:35:00Z

There hasn't been an easy way to check for management pack updates in Operations Manager 2007 until the R2 release. Once you're running R2, you can use the Import Management Packs wizard to determine if any of the MPs you are running have had an update released. Just follow the instructions on How to Import a Management Pack, and in step 4, be sure to select Updates available for management packs that are already imported on this computer.

Submit questions for the Operator's Manual

2009-06-09T20:14:00Z

There are two ways to approach content on using the Operations console and Web console for Operations Manager:

Explain what information is available in each section of the consoles.
Take examples of information that an operator would want to locate, and tell them how to find it in the consoles.

I've decided to do it both ways, in a guide that I'm putting together for new Ops Mgr operators. Here are a few questions for #2 that I harvested from an email discussion:

I have added a Management Group in the console and I also added few computers, how do I know if these computers belong to the management group that I added?
How do I know if a management pack is applied or connected to the servers that I added in the console?

What other questions might an operator want to answer in the console? Submit your suggestions to jdecker AT microsoft DOT com!

Is your IE8 slow to open a new tab?

2009-06-03T23:44:00Z

Whenever I would open a new tab in IE8, whether by control-clicking a link or simply clicking the New Tab tab, everything would go dead for a good 10-20 seconds until IE8would finally show a new tab and then begin trying to open something in it. (Yeah, it always feels like longer.) It finally began bothering me enough that I started searching for a fix.

The first suggestion I came upon had to do with the restricted sites list. Checked -- didn't have one.

The second suggestion was to run regsvr32 actxprxy.dll. Tried it -- no improvement.

(That doesn't mean that either of those fixes are wrong, it just means I have some other issue.)

I finally came across the fix that I needed in the comments to a post criticizing that second fix above. Add-ons! Clicked Tools -> Manage Add-Ons and there it was: ZuneIEPlugin.ZuneBHO, with a load time of 7.62 seconds. I disabled it and voilà! My tabs work nicely again.

If you too suffer from sluggish tabs, try those three suggestions and hopefully one of them will work for you as well!

MP Guide for Operations Manager 2007 R2

2009-06-03T22:46:00Z

The management pack guide for the Operations Manager Management Pack (Operations Manager 2007 R2 only) is available for download.

Usually, the guide is in the download with the management pack, but since the new Operations Manager Management Pack is included in the R2 product, we published the guide separately. We'll also be adding a link to the guide download to the System Center Pack Catalog, to make it easier for customer to find.

Note that if you are not running Ops Mgr R2, you do not want this guide!

What goes in product knowledge?

2009-06-03T00:53:00Z

When you create a component in a management pack, you have to provide a display name. You can also include a description and product knowledge. All three of those items are pretty much free-form, meaning you can put what you want in those fields (subject to character limitations, of course). That means that every MP developer has had to make decisions about when to use those fields and what to put in them.

That's just not a good use of a developer's time, and it also results in an inconsistent experience for customers using MPs from different developers. To help reduce that problem internally, we came up with guidelines for text in MPs: specifically, display names, descriptions, and product knowledge. One of our program managers suggested we provide similar guidance for developers and authors outside of Microsoft, so I cleaned it up (removed resources and links that are internal) and it's now available on OpsManJam: Guidelines for MP Text.

(edit: fixed typo)

Where did "Key Concepts" go?

2009-06-02T20:23:00Z

Back when Operations Manager 2007 was released, the content team posted an online version of a Key Concepts Guide and a download version. When you look at our documentation download page for Ops Mgr 2007 R2, Key Concepts isn't listed. Where did it go?

When the product was new, we wanted to highlight Key Concepts to clarify the differences between MOM 2005 and Ops Mgr 2007. With R2, we're not really a "new" product anymore. The explanations of model-based design, service modeling, and health modeling are primarily of value to the authoring experience. So, when we reorganized the content library in the R2 release, the Key Concepts content was added to the Management Pack Authoring Guide.

P.S. The links to the original content (first paragraph) still pull up the original content, but notice that the left navigation pane fails to resolve to a table of contents. Whenever you hit TechNet content and the navigation pane goes generic, you know you've reached deprecated content.

FizzBin for geeks

2009-03-21T09:09:00Z

Scott Hanselman has a suggestion for tech support -- a codeword that clues in the help desk that you kinda know what you're doing. I'm not sure fizzbin will catch on, but it's a nice dream...

Writing good technical documentation, part 2

2009-03-10T06:54:00Z

(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?"

Product knowledge in management packs

2009-01-13T00:37:00Z

Some components of management packs include product knowledge, which is just information provided by the MP author (as compared to company knowledge which is information provided by the user in their own copy of the MP). We're working on internal guidelines to help MP authors provide effective knowledge, so I'd like to know what your thoughts are -- what would you expect (hope) to learn from the product knowledge for any or all of the following components?

Management pack (the properties of a management pack can include product knowledge)
Discoveries
Rules
Monitors
Reports

Please leave a comment here or send email to mpgfeed@microsoft.com!

Writing good technical documentation, part 1

2009-01-07T09:40:00Z

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.

Spamming for computer equipment?

2008-12-20T03:40:00Z

Sometimes I read spam email before I delete it, just to see if anyone is getting more inventive. The recent trend is to claim to be from the FBI and to assure me that they've cleared my transactions with the foreign government.

I got a new one today, though. All this person wants, to release "my" funds, is two 120GB USB hard drives.

"I am Engineer Richard Mongo A Central Processing unit, known as computer scientist with African Development Bank. I am 29 years old, presently working with African Development Bank. I came across your file which was marked X and your released disk painted RED, I took time to study it and found out that youve met VIRTUALLY all fees and certificate but the fund has not been release to you. The most annoying thing is that they cannot tell you the truths that on no account will they ever release the fund to you; instead they let you spend money unnecessarily. I do not intend to work here all the days of my life, I can liberate this fund to you if you can abide by the rules and regulations to make this transfer successful to which ever method suits you, also promised to pay compensation of 10% percent of the total fund if I make you recover all what you might have lost in the past and help to re-establish your precedent bliss. The only thing I require to release this fund is a special HARD DISK we call it HD 120 GIG USB. I will need two of it to enable me recopy your transfer information, which I will destroy the previous one, and punch the computer to reflect in your bank within 24 banking hours and clean up the tracer then destroy your file, after which I will apply for resignation for my trip to your country for my percentage, or better still an ATM-CARD method payment can be granted if you are interested don't hesitate to get back urgently. You ought to send a convenient Tel/fax number of yours for uncomplicated communications and also reconfirm your banking details so that there won't be any inaccuracy. Note with the intention of your fund payment which has been taken to offshore for payment in other country are now mandated to offset by the Development Bank Of Africa due to the originator of your fund payment which is located here in the Africa continent."

I'm afraid I'm going to spend some time trying to figure out what precedent bliss is, and whether I really want it.

Active Directory Management Pack: which ones to import

2008-11-19T22:40:00Z

The latest Active Directory Management Pack package includes management packs for monitoring Windows 2000 Server, Windows Server 2003, and Windows Server 2008. Each server version has a .Discovery management pack and a .Monitoring management pack. You may decide that, since you're only monitoring Windows Server 2003 (for example), you won't bother importing any of the other server version management packs, only to have a problem because Operations Manager tells you that you're missing some required management packs -- what's going on?

Even if you are only planning to monitor one server version of Active Directory, you must still import all three .Discovery management packs. The monitoring management packs require all three discovery management packs to support the workflow for replication monitoring.

Authoring management packs

2008-11-07T01:13:00Z

Working on management pack guides, my attention is generally on how you can use the management packs we create at Microsoft. Next week, however, I'm attending a daylong workshop on authoring management packs. I'm hoping to learn a lot (unless it all goes over my head!).

But if I didn't have the opportunity of this workshop, how would I go about learning to create management packs? Well, first I would download the System Center Authoring Console. Next, I would download and read the Management Pack Authoring Guide. Finally, I would take advantage of all the great resources at the AuthorMPs site.

I'll let you know next week how the workshop goes!

ReadMe vs. Guide

2008-10-08T22:38:00Z

You might notice in the management pack guide library that some guides are quite extensive (like Active Directory) and some are a single webpage with "ReadMe" in the name (like FRS). You might also notice in the installation folder for some management packs that there are two documents: a guide and another that has MPAdd or ReadMe in the name.

What's going on with those? Last year and early this year, a number of MOM 2005 management packs were converted for Operations Manager 2007. When we released the converted management packs, we included the original documentation for the MOM 2005 management pack and added a supplementary document to provide any information that was unique to the converted management pack. Not rewriting the guides was primarily a resource decision, so we could make more management packs available more quickly.

What that means is if the supplementary document (which is specific to the Ops Mgr 2007 MP) says one thing and the guide (which was written for the original MP) says another, the supplementary document is correct. We just didn't explain that clearly enough in the supplementary documents.