November 2008 | HelpScribe

How to write a disaster recovery plan

Tragic events are a part of life. While we can't predict them, we can prepare for them. Here are some tips on how to write a disaster recovery plan that will keep your organization operating during and after such events.

Begin identifying the essential functions performed by your organization. Then, determine possible risks that would inhibit those functions.
Repeat the above process for key systems. Consider risks such as data loss, system failure, and so on. What impact will the failure or loss of such systems have on your business?
Assign or identify key people for handling recovery tasks and keep them involved in the process of drafting the recovery plan. They may offer valuable feedback about the details they'll need to handle a crisis.
Involve representatives from all departments when identifying risks. Each department will have different requirements for ensuring business continuity, and managers from inside each department will be better equipped to identify those needs.
Exercise your political skills. To write a thorough disaster recovery plan, you'll need to coordinate with people across many departments. Your ability to grease the wheels and extract information will be essential.
Document the location and purpose of any supporting documents for essential systems. For example, you don't want to waste time hunting for user manuals when your telephone system fails.
Revise your disaster plan based on actual testing. A live test of the plan will reveal any flaws, so that you can make improvements based on real data.
Establish a time frame for reviewing and updating your plan, and build such maintenance into your regular workflow. That way you can compensate for any changes in your essential business functions, environmental changes, regulations, and so on.

When you begin writing your plan, start with a thorough template. A template will help you create a robust and useful plan, and minimize the time you devote to tasks such as formatting and document organization. You can get a disaster recovery plan template here.

These tips will give you some guidance on how to write a disaster recovery plan that will keep your organization operating after a crisis.

Why I'd swap my spell checker for a better help API

If you are a technical writer worth your salt, you probably know your help content at least as well as your favorite novel. You've struggled over it for years, right?

But have you ever wondered how many of your help topics are actually read by users?

Scary question, I know. (Believe me, I know.)

The best content in the world is useless if nobody knows it exists.

Tracking tools aren't enough

Perhaps you've purged this inner worry by implementing server-side tracking software. Such server tools, often available from help authoring software vendors, can indeed tell you whether anyone reads your work. But statistics and user feedback may just confirm your fears; you still have to find a way to get more users viewing the help.

Embedded help vs. separate application

The root of this problem is the "help as a separate application" model of content delivery popularized by most help authoring tools. By separating instructional content from the application, we drastically reduce the chance of users actually seeing that content. We can't just assume everyone knows what the F1 key on their computer does.

Embedded help content would be a great solution. By putting help content, or links to relevant content, in the interface, more users are likely to find it. This is a wonderful option if the developers are willing to grant you some real estate in the interface. But we don't always have that luxury.

And that leads me to APIs.

Why APIs are the solution

Most professional help authoring tools provide a code interface that programmers can use to associate specific help topics with GUI elements. The API controls how the help is launched, including details like the size of the help window, where it appears on the screen, and so on.

Usually the API code is activated when a user presses F1 or CTRL+F1 from within a GUI element. This is where the plan falls apart. What if users haven't learned this convention?

Perhaps the APIs in help authoring tools could be modified so that when a GUI component has focus, especially for an extended period of time without user interaction, a help cue appears. This cue could be a simple prompt asking users if they need help, or even a hovering list of help links. Whatever the format is, it would need to balance being highly visible with being unobtrusive.

The key here is to ensure that this help cue is coded as part of a standard help authoring tool API, so that technical authors can ensure consistent help visibility regardless of the application.

If F1 and CTRL+F1 were marketing techniques, they would be the equivalent of sitting around waiting for customers to call and place an order. That isn't good enough. Your hard work deserves an API that can get content in front of users when they don't know how to ask for help.

Better APIs are the future of help.

About HelpScribe (and Craig Haiss)

Welcome to the HelpScribe Technical Writing blog.

I started HelpScribe in 2007 because I had a few ideas about how to improve user assistance, and I wanted to share those ideas with the rest of the technical writing community. Also, I wanted to meet others who shared those interests, and learn from their expertise.

Now, just a few years later, HelpScribe has been named one of the most influential technical writing blogs on the web, and has devoted readers around the globe.

HelpScribe.com contains articles on all aspects of technical writing, from help authoring to print documentation, and also on related subjects like Internet technology and technical writing gear.

When I'm not writing manuals, I spend my time reading dusty old novels, playing the guitar, and hanging out at parks with my wife and our two boys.

Hopefully you'll find something here you enjoy. If so, consider subscribing to the email or RSS feed, or sending a link to your friends.

Disclosure statement

HelpScribe.com contains affiliate links to products that I think you will find useful or interesting. These include links to document templates, books, and similar products. I make a small commission from purchases via these links, and from the advertisements on the post pages. These resources help keep HelpScribe.com free.

Why software development documentation matters

Software development is a complex process. As ideas are converted into actual code, the ability to alter the overall design is drastically reduced. Reworking ideas on paper is easy; however, rewriting many lines of code is inefficient. By providing detailed software development documentation early on, you can allow for sweeping changes in the design of the application.

Specs and requirements

Specs and requirements should be drawn up early on to define exactly what the application must accomplish. These documents will both guide the construction of the code, and allow for the development of thorough tests.

For more information on writing specs and requirements, see the following technical writing resources:

Technical writers can often assist in the process of developing specs and requirements by acting as usability advocates. By working through the specs, a writer can look for complicated processes that might cause user confusion, and help design ways around such pitfalls. Early interface work is especially ripe for a technical writer's skills.

I've found a great resource for software development document templates, including design documents, functional requirements, test plans, and more.

Abstract code and comments

When the specs are nailed down, initial coding is often done in an abstract language. An abstract language allows programmers to deal with the logic of a program without worrying about the details of a specific language. This abstract code is often turned into code comments as the real language-specific code is written.

Comments in the code are another area where technical writers can assist the development process. By reviewing the comments, a technical writer can clarify any confusing details, or look for missing information that would help future maintenance of the code. However, a writer will need to work closely with the developers to ensure the accuracy of their changes.

Well-commented code is essential for maintaining the application. Future programmers will depend on comments in the code to understand its purpose and structure. Also, comments are necessary for sharing information about dependencies and any expected input that the code needs to function.

Meeting minutes

Most development teams hold frequent meetings to discuss the design of software. Meeting minutes can be a valuable source of guidance for the development process. This is another area where technical writers can assist in the design process. By taking accurate and detailed meeting minutes, a technical writer can ensure that design plans are clearly recorded for later reference. Also, assisting in this fashion allows writers to have a more thorough understanding of how the application works when it comes time for writing documentation.

As you can see, software development documentation serves an important role in the design process. Writers can use this opportunity to leverage their skills in a way that benefits the entire team, and gain a deeper understanding of the functionality of the software.