Establish maintenance practices for your documentation

by Paul Baldwin | Mar 01, 2006 8:00:00 AM

Tags: Paul Baldwin

Takeaway: Just because you document a process doesn't mean you're finished. You must make sure your documentation is kept up-to-date. In this article, Paul Baldwin shows you why it's important to keep documentation current and some strategies for doing so.

Any aspiring astronaut, or any kid who dreamed of space travel, has seen the photo of Neil Armstrong's footprint on the moon. It's said that it will take micrometeorites millions of years before it fades into the lunar dust.

Your documentation, on the other hand, is about as permanent as a footprint on a beach. System upgrades, changes in business direction, and the users' varying needs make any permanence tied to documentation fleeting. Go back through a few years of your organization's documentation, and it's probably just a shade more valuable to your business than, say, a photo of an astronaut's footprint.

To keep your documentation from becoming an historical footnote for your business, put maintenance and update schedules in place. You'll ensure users have accurate direction and help maintain your documentation department's value. Here are a few guidelines.

Every month, every quarter, every year?

I once toured a former munitions plant that was trying to convert to civilian use after 30 years of production during the Cold War. As the property administrator took me on a tour of the sprawling property, he explained to me that every year "whether it needed it or not" the government would repave so many miles of road in the complex as part of the plant's efforts to keep a constant state of readiness.

Although it's doubtful you'll be able to redo the documentation equivalent of 10 miles of road, almost all of your documentation will need to be updated or replaced. Certainly, the plant had more resources at its disposal than most businesses. For a resource-strapped documentation department, your efforts will have to be more targeted. Deciding how to prioritize the work can help you manage the task.

Establishing a revision or update schedule is one way to ensure what's documented continues to be accurate. For example, you could divide your documentation efforts by department: In January, accounting's documentation is revised; in February, it's Training and Education's turn. Perhaps sharing your schedule with each department can help them organize their in preparation for your work.

Your ability to execute such a schedule will likely depend on the number of documents you and your staff is tasked to maintain, new projects requiring documentation, and other business shifts. Not surprisingly, updating your documentation on a schedule sometimes becomes a good intention instead of a realizable goal.

You may be able to estimate a ballpark figure of updates per month after a few months of tracking your efforts. Once you have numbers, set goals for your department or for each work. For example, each week you might revise 10 pages of documentation or you might update five documents from one department. If you can stay organized, adjust your figures every six months.

Individual-led updates

Understandably, it's easier to keep track of the documentation that you've put together personally. Three months after the project has wrapped, you know who to call to see if an update is warranted.

But if you've been handed a manual or a brochure covering a topic you've never seen, contact the author and ask for a list of people who helped validate the documentation. Ask if there were any unresolved issues that the author wanted to (or should have) included. Any major business initiatives coming soon? Changing systems? New governmental regulations? It never hurts to ask.

If your documentation is kept on a database, run a report to determine the documents and related materials that are being used the most. If you're pressed for time, updating a manual that's racked up 3,000 views will take precedence over the one that was viewed by three users.

Encourage your users to report problems

In the mid 1990s, many police departments implemented so-called Community Oriented Policing. The idea was to encourage police officers to develop relationships with residents on their beats so that when problems arose, it would be clear who they needed to contact to solve their problems.

In the same way, organizations should encourage their users to report issues with documentation. Let them know how and where to report issues and that errors and changes will be corrected quickly, and you'll have to spend less time searching out problems with your own work. If your organization is small, you might place an e-mail address in the cover sheets or footers that encourages users to e-mail problems to the person or department responsible for documentation.

If you organization is larger, Web-based feedback forms that let the user describe, for example, the problem, how it affects their job, and how soon the issue needs to be corrected can help you prioritize your documentation maintenance needs. It goes without saying that a reasonable turnaround time will help ensure users are willing to take the time to help you resolve issues. A simple fix, such as replacing a blurry screen shot, shouldn't take that long. Updating every screen shot in a 60-page manual will require more time.

You should also ensure that you report back to the users who reported the problem to let them know that the issue was addressed. And, lest you take someone's vigilance for granted, thank the person for pointing out the problem.

Links, phone numbers, employee names

In some instances, you can help your documentation age gracefully by what you leave out. If you want to make documentation writers cringe, show them a document peppered with links, phone numbers, and people's names--and then tell them to validate each one. (Maybe you can save this kind of project for the summer interns.) It's not as if this information isn't valuable, but it often has the unintended effect of revealing how quickly contact information changes. The key is to use such information judiciously. For example, a link to the home page of a Web site is a better choice than a link within the site because it's less likely to change. After all, you can still get to TechRepublic using www.techrepublic.com even thought the URL has changed to techrepublic.com.com.

E-mail addresses and phone numbers are even more temporary. One of the most common small changes that I make to documentation at my job is to change phone numbers that are no longer valid. E-mails that are tied to a particular user can also be problematic. If you can, refer users to lists, such as the directory tied to your e-mail system that are maintained as part of the business.

Use names sparingly, opting for titles instead. During a recent project my main contact changed three times during the six-months I was involved. If you can, use an employee's title instead of their name. There will always be a person who manages your accounting department, but it won't always be "Jane E. Smith, MBA."

Print/View all Posts Comments on this article

documentation practice samples might be helpfulhifimisi@...  | 05/08/07