Words and Software

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

July, 2006

  • Bullfighter for writing

    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

    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

    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

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

  • A peculiar behavior for agent install

    This is something you'll see more about in the next revision of the DPM FAQ. I don't have all of the details yet, but what happens is that you try to install an agent on a file server and the installation just seems to hang. Forever (or at least to the end of the administrator's patience...)

    What might be happening is an issue of the unsigned driver policy on the file server. You need to log on to the file server and clear the message so the installation can proceed, or change the policy.

    More details when this gets in the FAQ!

  • DPM and 64 bits

    A question came up in the DPM newsgroup that made me go "interesting! I hadn't thought of that possibly being an issue!", and of course I love being surprised by that sort of thing.

    The question was about SP1's support for 64-bit computers. "Can the same DPM server protect both 64-bit and 32-bit servers?" the customer asked, "Or do I need one DPM server protecting 32-bit servers and another protecting 64-bit servers?"

    I hadn't thought of it till then, but once the question was asked, I could see how one might wonder if that's how the 64-bit support would work. So I scanned through the posts eagerly to find the answer -- I was pretty sure the same DPM server would protect both, but not sure enough...

    Karandeep had already answered, of course: "With V1 SP1, the same instance of the DPM server will be able to protect 64-bit and 32-bit servers. You would not need another DPM server to protect 64-bit servers."

    (We tend to call DPM 2006 "V1" because we're working on "V2", which has no official name yet.)

  • TechNet Flash

    Do you subscribe to TechNet Flash? I've customized mine to include storage systems news, and the 12 July issue highlighted two new DPM papers: "Hurricane Season is here – are your branch offices protected?", which I was already aware of, and the provocatively named "Who is swapping your backup tapes – the County Clerk or the Councilman?", which I hadn't heard of and I'm going to read just because the title is so intriguing!

  • Ghosts in the report

    A customer removed a data source from a protection group and expected that to be the end of it. But, for what seemed like a long time, that data source continued to pop up in the reports. "I wouldst rid myself of this ghost," the customer proclaimed -- wait, he didn't say it exactly like that, but it's a Friday morning and the sun is shining.

    The point is the gap between the customer's expectation and the actuality. The gap is easily bridged by a simple explanation: the reports that included information about the deleted protection group member covered the period of time in which the data source was still being protected. Or, metaphorically speaking, the ghost is in those reports that include the time when it was still alive.

  • What's new in DPM SP1

    If you signed up for the DPM SP1 beta, you can download "What's New in DPM SP1?" now from Microsoft Connect. In summary, it covers the following changes included in SP1:

    • Support for 64-bit protection
    • Updated system requirements (to include R2)
    • Support for clustered servers
    • Protection for SIS-enabled servers
    • Interface for opting in to Microsoft Update
    • A fix that changes the default disk allocation formula

    I'll go into more detail into those changes over the next few weeks.

  • I tried Live.com

    I tried Live.com...and I like it!

    I had been using a personalized homepage on my.yahoo.com but I wasn't thrilled with it -- took a long time to load, and was constantly stealing my cursor (because I start typing in the search toolbar before the page fully loads...I'm impatient). (I think cursor-stealing is one of the most annoying webpage behaviors, btw.)

    I'd moved to my.yahoo.com from just using a search page as my homepage, and though my Yahoo page wasn't great, I had come to enjoy the convenience of having personalized information served up on my home page. So I was open to giving Live.com a chance.

    The opening screen was so clean...I really like that. Plus, it didn't make me sign in (I admit that I don't think it's necessary for people to sign in to things as often we -- Microsoft -- seem to require). Two points! So hoping that it wouldn't disappoint me, I clicked Personalize your homepage.

    I wasn't disappointed. It took almost no time at all to figure out how to set it up the way I liked it, and so far it's let me do everything that I want (except add links, but I haven't had time to really search for a solution for that yet so it could just be that I haven't figured it out but it's possible).

    With the tabbed pages, I can add whatever I want and still keep it clean. I can add and get rid of modules without going into "design" mode. Even drag-and-drop the modules to new locations while viewing. New homepage, I like it.