Documentation Project -- Getting Started

If you don't know where you are going -- your destination -- then it probably doesn't matter how, when, and where you get to one.

The same goes for a documentation project. You must have a goal. A final expectation. A destination. In the documentation world, this is usually called a "deadline".

And, of course, you will have milestones along the way that will let you know where you are and what you must do next to move along to the next milestone.

What's a "documentation project"?

For instance, in your writing class, when your instructor gives you a writing assignment, you are told a topic you must write about and the deadline for submitting the document. These may be the basic requirements for the document. The instructor may leave you with only those requirements and expect you to figure out the rest, or the instructor may be more specific by asking for a page count, page size, page margins, illustrations, line spacing, font size, and so on. They might even specify the number of references to cite and other requirements.

This example is not much different from what you'll find when you get out of school and into the world of work.

In journalism, such as writing for magazines and newspapers, the critical piece of the puzzle is the deadline. If you miss the deadline, you've missed the boat and lost the trophy (and yes, I know I'm mixing metaphors. But you get the point). Deadlines are all-important in the magazine and newspaper business--there's a time when the presses must run and any additional input must be stopped so the compositors and layout folks can create the final galleys for making the plates for the presses.

This is changing a lot with new technologies. With digital content development, composition, design, layout, and even typesetting, a lot of the different hand-offs during document production is eliminated. But the deadlines remain.

Similarly, in the corporate and business world, the documents also tend to have deadlines. But unlike the deadlines in media (newspaper and magazine printing plant deadlines), the deadlines in the corporate world can move in either direction frequently throughout the project. Yup, the project team (usually a "product team", and documentation is only a small part of this project) can pull back a deadline by a few weeks or even a month to accommodate an early beta release of the product. Or, because they've had some problems in engineering, they'll slip the project deadline for a few weeks or a month or two to allow them to do some "bug scrubs" and "bug fixes".

So, you may wonder, "How in the world do you plan a documentation project with this kind of behavior exhibited by all the players?"

From the previous two posts, you might think that you know the "metrics" and "brainstorming" for a documentation project. But when presented with the vagaries of documentation as described in this post, you will again be at a loss.

Does it happen like this on construction projects? Where the participants all know the cubic yards of concrete required for the foundation (and also know the drying times for the specific kind of concrete), the linear feet of rebar reinforcements for that same concrete, the amount of lumber yardage, plumbing fixtures, and even down to amount of nails and fasteners?

There seems to be a difference.

Construction Projects

When notified that you'd be working on a construction project, if you were an experience construction professional, you'd scope out the area where the construction would take place or the building to which the remodeling would happen. You'd get your environmental impact assessment reports, your soil analyses, your county surveyor's records, and your zoning requirements all gotten together and assembled. Then, you'd walk the area and scope out the project--the general area and dimensions of the project, the elevation of the project, and a loose estimate of the materials, the number of workers, and the time needed to complete the project. According to one of my tech writing instructors, this would be called a "SWAG--Scientific Wild-Assed-Guess"--good for a "ball-park" estimate to start with putting form to the idea of the project.

Then you'd get down to the detailed nitty-gritty analysis of the project. You'd develop the various engineering drawing layers--for the grading and trenching of the lot area, for the reinforcing rebar and foundation, for the framing, for the electrical and plumbing, for the walls, for the roof, for the drop-ceiling, for the ventilation, for the doors/windows, and so on. Then, you'd calculate the number of cubic yards of concrete; the linear feet of rebar, lumber, electrical wiring, plumbing, and masonry; and for amount of fasteners, nails, paint, stucco, and finishing touches. These figures would then be added for the material costs. Then, you'd need to create timeline based on the size of your construction crew--the number of workers determines how fast you can grade the area, dig the trenches, lay the rebar, pour the concrete, put in the framing, add the roof, add the walls, add the doors and windows, and complete the finishing. Other factors determine the timing of your project that have nothing to do with the number of your workers--these would include the physics of drying concrete and drying paint.

From all these component calculations -- for the engineering drawings, for the estimates derived from those drawings on needed materials, for the industry-established timing metrics for the tasks involved with the project, and for the number of workers allotted for the project, you can come up with a project budget and timeline with milestones and the deadline. The deadline may be a little flexible with certain jobs that could be worked on simultaneously or by adding additional workers, but the project timeline would be a somewhat dependable indication of when the project would be completed. You could even add these figures to project calculation software, perhaps like Microsoft Project, to make nice charts in various forms such as Gantt Charts or PERT Charts that would show all the timelines heading for the various milestones and the ultimate deadline of completion. The dependencies would be shown and the chart would make it easy to see where compression of tasks could occur to make the project most efficient and where savings could be implemented.

Documentation Project

Yeah, they may know that they want a document (but sometimes even that isn't happening). And then they tell you when they want it -- their deadline. And they tell you a day before they need it. Well, maybe not that bad, but sometimes it seems they pull their deadline out of their hat (or from somewhere else). And they haven't taken account of the complexity of their subject matter, the availability of their subject matter experts or reference sources, the availability of illustrations or an illustrator, or the number of pages they need to create. But they have their deadline.

And they'll tell you. They want a 100-page document pushed out with a month-long deadline. Sure, they'll tell you what they want for a topic. They may provide you with some research materials and some subject matter experts to talk to. But you are going to need to ask them a lot of tough questions to clarify what they want and why they want it (sometimes they don't know why, but they feel they need it). Who is the intended audience? What is their reading level and need for the information? How many illustrations will you need? Is someone available to help with the illustrations, or do they expect you to do them? Is there a document template, or will you need to create one?

You can try to put this information into a Microsoft Project application file, but because the application depends on adding the metrics to come up with a deadline (as how it's designed to do... and it works quite well with construction projects) rather than stating a deadline and then just faking the timelines all based on the deadline, this only creates a pretty diagram that is essentially meaningless.

Sort of.

Most professional tech writers can, nevertheless work from that pretty schedule and produce a document within the required deadline. But in most cases this isn't cheap--particularly if they are concerned about quality.

Eventually those who want to have a document produced will learn that they can have their documentation project with three major criteria:
cheap, quick, and quality.

The problem is... without good planning and scheduling, only two of those options are options. One of them will always have to go as an expense of the others.