Corporate Intranet

Creating a documentation plan involves scoping all aspects of a writing project before you start the actual writing.

If you avoid this step, you run the risk of missing a key deliverable, or assuming that another team will jump in at the last minute and assist you in completing the documentation. This may work in a small company where things are more flexible but if you work in a process-driven work environment, this is unlikely to occur.

Also, if you work as a freelance writer or consultant, you need to get these assumptions clarified before you start. Otherwise this may be disagreements between what the client expects of you and what you assumed of them. Get it all down on paper!

Inexperienced writers make the mistake of starting their writing without any planning. Very soon they loose their bearings and miss deadlines.

Let's look at how a documentation plan, also known as a writing plan, can help you manage writing projects, especially those that span several months and require input from different writers, editors, reviewers and so forth.

Why planning is so important

Use the documentation plan to outline YOUR requirements and the risks that may arise if these are not met. Highlight the contingencies for each risk.

Here are some typical requirements:

3 copies of Madcap Flare for writing Online HelpTesters to test the final documentsGraphic designer to prepare the imagerySecurity clearance and authorization to visit the company HQ

Other things to consider may include: access to physical buildings; travel arrangements if the project involves travel.

Unless these are stated up front, your project runs the risk of missing deliverables, coming in late, producing invalid documents or requiring additional resources to be completed on time.

Poor planning will not inspire confidence in your manager and reflect poorly on you as a professional writer.

Starting a writing project

Before starting a large-scale project, ensure that your documentation plan covers the following areas:

1. Communications - describe how you will inform the Project Manager, Team Leads and other parties on the status of each documentation deliverable. Failure to communicate project issues early may lead to your, and other, deliverables missing their due dates.

Also, by pro-actively communicating the status of your project, including whatever risks/issues that may arise, your colleagues will feel that you are in control of this project and have successfully managed each deadline.

2. Schedule - this part of the documentation plan effects other departments. In here you outline the number of days (man-hours) required to complete this project. This figure will be used to prepare costs and project estimates.

Illustrate this by showing the number of days for each writer by week, month and deliverable.

For example, show that you need Jane Royce for 90 work days; 30 days for each User, Admin and Install guide. If necessary, illustrate where your project overlaps with another project and the contingencies you have suggested as a workaround. This may arise if your company shares writers (and other reasons) between projects.

3. Deliverables - provide exact details of the actual deliverables. It is not enough to say "we're writing the guides for the next 3 months", you need to break out each guide by formal title; estimated page count, word count, graphics; page size, tools, and delivery format.

Some documents may be delivered in Word, others will be provided as PDF, XML and Online Help. Make sure YOU understand exactly what is required and plan accordingly.

For example: The final deliverables for the release of the Solution 2.0 are a System Admin Guide, Online Help, Datasheets, and a Quick Start Guide. These will be delivered in US English in PDF and Online Help format.

Once you have prepared your documentation plan, circulate it to all reviewers. Request that they review it by a specific date - otherwise they may just ignore it.

4. Roles and Responsibilities - make it very clear what you expect from each team member during the course of a writing project. This means ALL contributors, not just your writing team.

Identify what you expect from the testers, developers, designers, and most importantly, those who will review the final documents. They have to agree to this before the documentation plan is signed off, otherwise your project is already at risk.

5. Resource - outline all the resources you require; this includes human (writers etc), software, hardware and others as necessary. For example, you may need Adobe Framemaker for writing long documents. If so, what are the licensing costs? Can the budget afford this? You cannot proceed unless you have received confirmation that funds will be allocated. Otherwise, you need to look at alternatives.

Getting it signed off

Examine the feedback you get back and discuss whatever issues that have arisen.

Confirm with them that they understand what's expected of them, especially if they are new to the company and may be used to different work practices.

Once all are in agreement, update the final plan and circulate it. You may want to publish it to the Intranet so it's easy to access.

Finally, always leave some contingency for items you may have overlooked. No one will be upset if you come in before schedule but there will be little sympathy if you come in late.

Give your project every chance to success.