Recently, one of my contracting clients migrated its corporate network from NT4 to Windows 2000. The plan included a two-week, gradual migration of thousands of users from the NT domain to the Windows 2000 production domain.

One of the network administrators wrote a set of instructions aimed at guiding end users through the process of migrating their user profiles. On the first day of the rollout, the help desk was flooded with dozens of calls from angry, frustrated users who complained, “the instructions don’t work!”

While the document was well written and well organized, it was clear that a techie wrote it for fellow techies, not for end users. I was given a half-day to rewrite the instructions and create a more user-friendly document to be sent to the remainder of the end users.

The new instructions apparently did the trick, as the number of calls to the help desk fell to a handful per day during the remainder of the scheduled rollout. This week, I’d like to give you some ideas for writing your internal how-to documentation by sharing some of the “before” and “after” text written for this client’s migration.

The task
Users running Windows 95 received a document with exceedingly simple instructions: At the logon screen, change the entry in the Domain field from the old NT domain to the new Windows 2000 domain.

For users running Windows NT Workstation or Windows 2000, the instructions were a bit trickier. Here is a summary of what those end users were expected to do:

  1. Log on to the new (Windows 2000) domain for the first time.
  2. Log out.
  3. Log on to the old (NT) domain, then copy the user profile to the appropriate location.
  4. Log off the old domain for, hopefully, the last time, then log back on to the Windows 2000 domain.

On the first day of the rollout, one of the biggest problems observed by the help desk was that users were copying the profiles into the wrong locations. For users running Windows 2000, the destination is C:\Document and Settings. For users running Windows NT Workstation, it’s a folder located under C:\WINNT\Profiles\.

Just say it
Users had difficulty following the original instructions because they contained too much technical jargon. Let’s start by looking at the text contained in the original “introduction/purpose” section that was delivered to the first batch of users. (The names of the domains have been changed to generic OldProd and NewProd.)

The original instructions
Introduction: These instructions will guide the users of MS NT 4.0 Workstations (NTWS) and MS Windows 2000 Professional Workstations (W2KP) through the first time they authenticate to the NewProd domain. This first logon will create another local user profile for the user on the workstation due to the different security identifiers (SIDs) associated with this different domain. These instructions will then guide these users through the process of copying their old local user profile over to their new profile so their personal workstation configuration is the same as before the change of domain logon.
Purpose: The purpose of these instructions is to support the migration of all corporate users from authenticating to the Old NT domain to the Active Directory NewProd domain in such a manner as to be as seamless to the NTWS and W2KP users as possible. These instructions will provide the user with the necessary information to achieve this conversion in a uniform and timely manner.

Is it any wonder end users were confused about what they were doing and why? When I tackled rewriting the instructions, the first thing I did was compose an executive summary that leaves out jargon and gets straight to the point:

The rewrite
Why do we have to upgrade our profiles?
The company’s IS department has upgraded the corporate network software from Windows NT4 to Windows 2000. As a result, we will be phasing out the old network domain, OldProd, and moving all users to the new domain, NewProd. These instructions will guide you through the process.

Going for the top-down approach
After the introduction, the second big problem was that the original step-by-step instructions were written like spaghetti code instead of in a top-down fashion. To illustrate this point, check out the Table of Contents from the original document:

The original instructions
Part I: Sequence of events for first logon and profile migration
Part II: Log on to the NewProd domain for both NTWS and W2KP
Part III: Migrating the local user profile on a W2KP after first logon to new domain
Part IV: Migrating the local user profile on an NTWS after first logon to new domain

On the face of it, those parts look like they follow a logical order. Users became confused, however, when the first set of instructions under Part I looked like this:

The original instructions
1. Log on to the NewProd domain for first time. (See Part II.)
2. New local profile is created automatically during first logon.
3. Log off from workstation.
4. Log on to workstation using OldProd account. (See Part III or IV.)
5. Copy old local profile to the new local profile. (See Part III or IV.)
6. Log off from workstation.
7. Log on to the NewProd domain and use this account for now on. (See Part II.)

Lead me down a straight line, please
All of those parenthetical instructions—the spaghetti code component of this documentation—confused people. Users don’t want to bounce around from this part to that part. They want to start with the first step and work their way down to the last step. To that end, here’s how I rewrote the Table of Contents:

The rewrite
Step 1: Determine what operating system is running on your computer.
Step 2: Log on to NewProd for the first time.
Step 3: Don’t be surprised when the desktop looks different.
Step 4: Log off and then log back on to OldProd.
     Step 4a: If you use Windows 2000
     Step 4b: If you use Windows NT
Step 5: Copy your profile.
     Step 5a: If you use Windows 2000
     Step 5b: If you use Windows NT

Don’t forget the FAQ section
I am happy to report that end users seemed to respond more favorably to the revised, user-friendly document than they did to the original set of instructions. However, after the third wave of users had been asked to migrate, we added one more section to the document that further reduced the number of help desk calls. In this section, we answered some of the frequently asked questions that arose as users tried to migrate their profiles.

There was one significant issue that came up a number of times, and if you’ve been through an upgrade from NT4 to Windows 2000, you’ve probably already heard about it. If you’re planning such a migration, remember to include this tidbit in your documentation: What happens if you receive an error about insufficient disk space?

Instead of telling users to call the help desk, we added a page that explains why that error can occur—typically because the user has too many files stored in the Personal, Temporary Internet, or Cookies folders—and what the user can do to perform cleanup on the disk.

Get an end user’s opinion
The lesson here is simple: Write to your audience, not to your peers.

The author of those original instructions captured all the right screen shots and included all the right information. However, the document had been reviewed and approved by IT people, not by typical end users.

The next time you need to issue step-by-step instructions to your end users, ask a few of them to review the document for ease of use before you send it out.

Share your migration tips

To comment on this tip, start a discussion below or write to Jeff.