Internal Documentation: Before and After

Here’s a quick example of the difference you can see when you apply the basic principles of tech writing (maintaining a user-centric focus, dividing tasks into usable chunks) to documentation written by a sys admin.


There’s some good stuff in here—the original author gives us helpful hints and lots of screen shots—but the organization is pretty wonky, rendering the whole thing pretty unusable. Essential steps are left out, and other steps just aren’t clear. And of course there’s a healthy dose of typos in the mix. (“Signon”—is that French?)


After killing the typos and committing to a consistent voice, my cleanup focused on restructuring the content:

  • Step-by-step tasks and descriptive material each have their own turf.
  • The sidebar about bookmarking the site is nifty, but since it’s something you’d only do once, it makes more sense outside of the sign-in procedure.

and adding important information:

  • Everyone in IT knew that the system only worked with Internet Explorer, but users had to find out by word of mouth. This might be a good thing to mention in the user guide.
  • A few more screen shots clarify the steps and support the new structure.

Audience: business professionals

Industry: medical

Previous post:

Next post: