Wait, don't panic! This is not going to be a long and tedious lesson on writing techniques. For a complete overview of good writing, you may want to refer to the classic, The Elements of Style by William Strunk, Jr. & E.B. White before you read this issue of "A Note From The DocuDoctor." This newsletter is going to take a look at how to make a document concise. Intrigued? We certainly are!

Let's start with a basic definition of "concise" from Merriam-Webster's online dictionary (http://www.m-w.com):

How do we make a technical document concise? Let's consider two aspects of the technical document, its structure and its content. The structure of a technical document encompasses the table of contents (TOC), the chapter and section headings, and the physical layout. The content is the information and technical content the document is to convey to the reader. Did you realize that a carefully structured document can better facilitate a concisely written document?

Join us now for today's DocuDrama...

If you've been in this field for any length of time, you have probably been handed a document and told, "This was written by Rex D. Techwriter just before he quit. Would you take a few moments and clean it up for us!?" "Hmm," you think to yourself. "Was Rex following the DocuDoctor's prescriptions for developing good documentation right up until his departure from the job?" Probably not!

Once the feeling of overwhelming hopelessness subsides and you've come to grips with the fact that Rex was actually a summer intern and phys ed major from the nearby junior college, you can begin to tackle the problem. The (your) problem is to take Rex's document and transform it into a concisely structured and written one (i.e., fix it!). Don't forget that you must read Rex's document cover to cover. This is the only way to determine what needs to be fixed and how extensive your repair effort will be. Give it a good objective review and take notes on what you find. You may need these notes later to justify to your boss why the document needed so much rework.

Now remember that we have already touched upon many of the criteria in previous newsletters to make a technical document a good one. If you think that a design review is warranted to help you define the task at hand, revisit the newsletter "The Design Review." Or perhaps one of the other previous DocuDoctor's newsletters may provide you with some ideas on making your task easier. (Visit The DocuDoctor's page at http://www.msd-corp.com.)

Does The Document's Table of Contents (TOC) Make Sense?

We all know that a TOC is intended to list the main topics and sections with the page numbers for each. If a TOC does not appear to match the type of document or the document's subject matter, then it may not be properly developed. Your document's TOC should always be concise by presenting a single idea or topic in each heading. If the headings appear long or contain multiple topics, you may have a faulty TOC.

Your task is to now do a little research. Spend some time with the engineers or end-users, or any other subject matter expert (SME) to find out what he/she considers to be the important topics for Rex's (and now your) document. Remember to take notes so you too can become a SME.

Ok, so you've read through the document and you have learned a fair amount about the subject matter. Let's revisit the TOC to see if any noticeable gaps exist in the main topics and sections that are listed. In other words, verify that all or most of the important main topics appear in the TOC. If they do appear, are they brief and to the point?

Let's assume that the important main topics do not appear in the TOC, (for the sake of this newsletter's unfolding drama). You may wish to create a new TOC for the document from what you've learned about the subject and from the TOC from the original document. Run your new TOC by your managers, engineers, and peers for their opinions (perhaps in a design review), and you should have a pretty good TOC for your new and improved document. (Too bad Rex isn't around to see how it SHOULD be done)!

Re-organize, Re-sort, and Revitalize!

Now it's time to transform that old document into one that is structurally healthy. With your new TOC tacked up on the wall in front of you, start reading through Rex's document to identify sentences and paragraphs that relate to at least one topic in your TOC. What you want to do here is identify where in the old document specific ideas and discussions are presented. Once you make your way through the entire document, you'll have a good idea of what you need to do.

So, let's start creating your new document by copying and pasting the sentences and paragraphs you have marked above from the old document into the new document Make certain you move the text under the appropriate (and carefully worded) headings in your new TOC. If a sentence or paragraph contains two or more ideas that fit under two or more of your headings, copy it into both places. You can go in later and edit the paragraphs as needed.

You have now gone through Rex's entire document and moved all of his paragraphs to your new and carefully structured document. If there are any headings with little or no text underneath, it means that Rex left out some really important information that your document should not be without. You know where the "holes" or missing information are and you have copied all of the existing information into your own document. Now it's time to start writing that document as if it were your own.

Just a Few Pointers...

You now have a good, solid structure for the document. So, let's start to write, rewrite, and edit our paragraphs so that each support its corresponding heading. Here are a few pointers to keep in mind as you move from being "Rex's replacement" to the "indispensable tech writer."

Need More Proof?

So why be concise in your writing? Aside from building your own reputation and salary, there are quite a few reasons. Here are just a few things to consider:

And, so concludes another titillating docudrama in which our stars (you, the tech writers, of course) are all rewarded for a job well done with more documentation to develop. As for Rex, he decided to steer his career path away from technical documentation. Watch for his upcoming exercise video for computer programmers, "Burning Calories at the Keyboard."

The next newsletter in this series will be "Types of Deliveries" which will discuss how and when document versions are released. Upcoming titles and previous issues in the series "How to Save A Quarter Million On Your Documentation Tasks" may be found on The DocuDoctor's page of MSD's web site.