Words and Software

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

The path of an error message

The path of an error message

  • Comments 1
  • Likes

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.
Comments

  • Wow, thanks for the example: I always knew that “someone” was translating the Microsoft Engineers’ original words!

    We were once trying to solve an Outlook problem of not saving the username. The username field would come up blank on some computers. We tried searching for everything (blank field, empty field etc.) – we are still scratching our heads that the “proper” Microsoft word for a “blank field” is “unpopulated!” KB198438