Words and Software

Technical writing/user assistance in Microsoft.Azure Intelligent Systems Service (ISS). (old: Data Protection Manager and Operations Manager)

September, 2005

  • Process flows and content design

    Yesterday I sat in with some folks working on the next version of SMS to observe their approach to process flow and documentation. (I don't want to be leaking feature information that might not be ready for public release yet, so I'm going to use the fictional "verning" instead.)

    The key players were the writing team and the verning expert. The lead technical writer had already assembled a rough process flow from the verning specification, and placed each step on its own Post-it® on the whiteboard.

    The verning expert began by pointing out that, although the steps on the board were all sequential and part of the overall process, they actually fell logically into four different stages: planning, preparing, doing, following up. (Writers love it when information organizes itself so neatly!)

    And that's why Post-its® are so handy - just takes a moment to rearrange them to suit the new approach. Now, with our four sets of steps, the expert begins explaining and the writers ask questions to clarify and to make sure the flow accounts for everything the customer will need to know or do. New Post-its® are added as we go.

    "I have plinking first - is there anything I should have done before that?"

    "What other ways could the customer do that?"

    "We're telling them to connect to the plonking point, but that isn't in planning - do they need to do something earlier about plonking?"

    "What are their choices at this step? What decisions do they have to make?" 

    The design phase is such fun.

  • Today's 'duh' moment: Outlook

    After using Outlook for so many years, I thought I'd figured out all of the shortcuts and tricks I needed for the way I work, but somehow a little feature crept in without my notice that I discovered by accident today.

    I use a lot of folders to organize my Inbox. Some emails go to the correct folder by Rules, and the rest I drag and drop. Today, as I moved my mouse, I discovered that the "Move to Folder" icon had listed all of the folders I used recently - I swear I've never seen that icon or its menu before! And so, my duh moment: fewer therbligs to mouse-over and click a folder name to move the selected email than my previous method of dragging the email down through the tree.

    12 Oct: edited to change source of screenshot...my other method just wouldn't work consistently

  • "80/20" and content

    "80/20" is a ubiquitous principle (formula, law, etc.) that lends itself to statements such as "80% of a business's performance problems are due to 20% of the employees" and "80% of annual traffic accidents are caused by 20% of a region's drivers". (You can tell I made that last one up, right?)

    We even use it in content planning. But before I write about how we apply it, I decided to poke around and find the origins of 80/20.

    Wikipedia tells me that the economist Vilfredo Pareto claimed that 80% of property in Italy was owned by 20% of the Italian population. Joseph Juran, a management specialist, extrapolated that ratio into a principle: "for many phenomena 80% of consequences stem from 20% of the causes." An even clearer explanation puts it this way: "The 80/20 Rule means that in anything a few (20 percent) are vital and many(80 percent) are trivial."

    The benefit of thinking about 80/20 is as a guideline for where to concentrate your efforts. So in content planning, it's a rule of thumb for filtering content: does this topic address an issue 80% of our customers are likely to encounter?

    You might ask, why does that matter? For the customer, it matters because content they don't want to know is irrelevant and irrelevant content is noise, an obstacle. For us, in addition to doing what's best for the customer, there are limitations such as a time and money. We need to focus our schedule and budget on providing information that will help the largest group of customers.

    Of course it isn't exact, rules of thumb never are. Maybe only half our customers will ever do Procedure X - that's more than 20%, let's cover it. But when we come across a scenario that applies to 1 in 10 at best, we flag it for further consideration, because then we need to drill down further on areas such as risk and potential damage and whether there are other ways of dealing with it.

    Maybe that's another application...80% of product information ends up in core documentation, 20% is managed separately...?

    And now I'm wondering...do 80% of our customers read only 20% (or less) of our content?    

  • Check out our new TechNet page!

    The DPM TechNet page is sporting a new look and lots of new links. There's the usual "Contact us" link, but we invite you to email us directly at Dpmfdbk@microsoft.com with any feedback or suggestions for the site.

  • DPM's MVP*

    *MVP = Most Valuable Professional

    I planned to introduce the MVP for DPM, Joseph Bittman, in this blog this week in recognition of the Microsoft MVP Summit. Well, the timing is due to the Summit, the reason for introducing Joseph is because of the high regard our team has for him.

    Then I noticed that Joseph was featured in this week's Micronews (our internal newsletter). To increase the coincidence factor, the article is about Joseph becoming a technical reviewer for Microsoft Learning, where I worked before moving to the DPM group, and it quotes Jim Cochran, a technologist I worked with for several years. I can't repost the Micronews interview here, so you get my version.

    You may be wondering why Joseph was interviewed for the Micronews -- surely every new MVP isn't announced company-wide? Not even every MVP who becomes a technical reviewer. And you'd be correct. The added human-interest dimension that makes Joseph newsworthy is his age. Which we didn't know when the product team began mentioning him as the best DPM candidate. All anybody knew was that this person had jumped into the DPM beta testing with both feet, devouring the documentation, trying every procedure, filing the most bugs, posting frequently in the newsgroup, asking intelligent questions, and offering help to other beta customers. It was pretty obvious that he was an outstanding candidate.

    To make a long story short, when our release manager approached Joseph about being our MVP, that's when we found out that he was (at the time) 14 years old. He qualified through performance, and I really love it when performance trumps other criteria. Some of Joseph's other accomplishments:

  • Status: DPM FAQ and beta upgrade instructions

    I mentioned that the DPM FAQ would be published shortly and that it would contain the instructions for upgrading DPM beta to the release version. I was only partially correct.

    We're posting the FAQ so that it will be available at launch (it will replace the Beta FAQ on the DPM TechNet page, but it will not contain the beta upgrade instructions.

    Why no beta upgrade instructions? First, let me assure you that we will be adding the instructions for beta upgrade and Evaluation edition upgrade as soon as possible. However, for you to upgrade your beta installation and retain your replicas, you will need to download and run a tool that our team created. The tool will ensure that your beta replicas will be compatible with the released version of DPM. Testing on the tool is complete, and now we're going through the process of getting it loaded to the Download Center. But I can't complete the upgrade instructions without including the link to the tool - that would be rather frustrating for you! So I'm waiting for the link.

    In the meantime, we want the rest of the information in the updated FAQ to be available with the product launch. We will refresh the FAQ with the upgrade instructions as soon as the tool is available for download. Stay tuned...

  • Can ignorance serve a purpose?

    Perhaps a more precise question would be, can technical knowledge impede a technical writer's effectiveness?

    A recent article on BBC News, "Computer terms confuse workers, reports that a survey showed that "three quarters of workers waste more than an hour a week deciphering what a technical term means." The same page links to similar articles:

    • "Geek speak confuses net users" (Apr 05)
    • "Hi-tech babble baffles many" (Jul 03)
    • "People confused by wi-fi jargon" (Aug 03)

    I don't think that problem is news anymore. It can be argued that this is why technical writers are needed: to translate technical terms (geek speak, hi-tech babble, jargon) into language the user can understand.

    But as you learn those technical terms so you can write about them, they become familiar. And after awhile, you can forget that they might be a foreign language to some people. Take the examples given in the BBC News article:

    "Terms such as jpeg, javascript and cookies are among the problem words highlighted by the firm Computer People."

    Easy to think, "well, everyone knows those" and be wrong.

    So when I need to write documentation for a novice home user, one who may not have any significant computer experience, I pretend I'm writing for my mother. Writing for an experienced audience, such as system administrators, is more challenging; if I know a certain term, shouldn't they? That isn't a safe rule of thumb. At the same time, there's a need to balance the benefits of defining a term (just in case) against the risk of losing your audience by writing down to them.

    And the pitfalls multiply as the sophistication of your audience increases. Writing for system engineers, architects, developers...more and more you have to rely on your subject matter expert to point out that you may not know that word but your audience does.

    Documentation should clearly state its intended audience so readers can gauge their ability to grasp it. Writers should have a thorough and accurate understanding of their audience. And writers must somehow learn technology while retaining a technical innocence so they can be in the reader's mindset as much as in their own.

  • The path of an error message

    We all want error messages to be useful. Here's a look at how a single DPM error message changed as it went through reviews.

    The original message From the disks tab in the Management task area, check the status of the disks.
    The developer suggests a change From the disks tab in the Management task area, check the status of the disks. Rescan the disk configuration to detect this disk. If the disk is not found, verify physical disk connections and perform Rescan again. If the disk is no longer available, then you may remove this disk. After the disk is removed, proceed to the Protection page to reallocate the protected volumes on this disk.
    A program manager adds some clarifying words From the disks tab in the Management task area, check the status of the disks. Rescan the disk configuration to detect this disk. If the disk is not found, verify physical disk connections and perform Rescan again. If the disk is no longer available, then you may remove this disk from the storage pool. After the disk is removed from the storage pool, proceed to the Protection page to reallocate the protected volumes on this disk.
    Technical writer modifies the message From the disks tab in the Management task area, check the status of the disks. Rescan the disk configuration to detect this disk. If the disk is not found, verify physical disk connections and perform Rescan again. If the disk is no longer available, to continue protecting data for the affected volumes, you must remove this disk from the storage pool. After the disk is removed from the storage pool, use the Protection task area to reallocate the protected volumes on this disk.
    Editor has input From the Disks tab in the Management task area, check the status of the disks. Rescan the disk configuration to detect this disk. If the disk is not found, verify physical disk connections and perform Rescan again. If the disk is no longer available, you must remove this disk from the storage pool in order to continue protecting data for the affected volumes. After the disk is removed from the storage pool, use the Protection task area to reallocate the protected volumes on this disk.
    Editor and writer discuss offline and submit this version to the developer From the Disks tab in the Management task area, check the status of disks. If a disk is missing, rescan the disk configuration to detect the disk. If the disk is still missing, verify physical disk connections and perform Rescan again. If the disk is no longer available, you can remove the disk from the storage pool. To continue protecting the affected data, use the Protection task area to reallocate the protected volumes.
    Not all error messages were that simple, of course.
  • DPM Ops Guide goes live!

    Data Protection Manager 2006 will be launched next week. And we made our commitment: the DPM Operations Guide is live and online in advance of launch.

    This is our final piece of major product documentation. The Planning and Deployment Guide and Help were made available earlier this summer.

    Still to come: DPM Frequently Asked Questions, which will contain instructions for upgrading DPM beta to the released version.