Preparing drafts

From TechWriter Wiki

Jump to: navigation, search

Contents

Introduction

In 'olden times', a Technical Communicator would draft the words for a technical publication. These words would then be checked by an editor (sometimes after having been keyed in by a typist). Once the document had been checked and corrected (any number of times) the final text would be submitted to the DTP department, who would merge the words and the illustrations (prepared separately by the Illustrator) into the final document, and print off the camera-ready copy.

Nowadays, many Technical Communicators are working as one-man operations, and are writing, editing and doing the DTP work themselves. They may even be knocking up the occasional illustration to boot. With the Technical Communicator now producing the camera-ready-copy, one might wonder what is the purpose of producing a draft, especially when you know that the document is technically correct. This page provides some arguments as to why drafting is a good idea, and highlights some of the uses of a draft.

What is a draft?

Put simply, a draft is a version of a document that is not the final (publishable) version. For many clients, any version of a document that has not been signed off is a `draft', and normally must be clearly identified as such. Often, there is a certain amount of `liability limitation' behind this oversimplified categorization; the organization (or the author) is kind of saying "Don't blame us if the content is wrong - after all, it is only a draft!". This is not a helpful categorization, therefore, as it presupposes a certain amount of inaccuracy in the document, when drafts should be no less accurate than the finished version.

Instead, it is better to think of a draft as a `work in progress'. The draft is then simply a way of allowing the client to check that progress is being made in the right direction. If a document is turning into something different from what the client had in mind, then it is better to identify this sooner rather than later. If such discrepancies are identified at the draft stage, then it is relatively easier to correct them (certainly more so than finding out when you deliver a 100-page technical manual that what the client wanted was a quick reference card!).

A draft should give the client (whether this is the commissioner, the Subject Matter Expert or the end-user) the opportunity to see what will be produced and to identify any errors or omissions. Drafts also provide an excellent opportunity for the client to suggest improvements - incorporating these at the draft stage will typically be much easier (and therefore more likely to get done) than once the document has been finalized.

Can be treated as a trigger for discussions.

Uses of a draft

  • Planning the appearance of the document
  • To provide 'advance information' - but in this case it is essential that recipient knows this
  • To allow the planning of translations (size/complexity)
  • Testing (of the system and the documentation)

Writing the draft

  • Overriding: Don't write too soon
  • Check technical accuracy with the engineers or designers
  • If an action or operation is difficult to explain, tell the designers - it may be due to something they have overlooked
  • Make sure that documentation applies only to one model (or differences are clearly indicated)
  • Have a clear indication of the terminology to use

Numbering drafts

The exact stage of this progress will typically be defined by the client, and different version numbers may be assigned to the document at different stages. For example, a client could request the following draft versions to be delivered:

  • Draft 1: Section headings and order defined
  • Draft 2: Text written, but no illustrations
  • Draft 3: Text and illustrations in correct position

Alternatively, the draft number could simply be an incremental counter used to identify the number of changes (and - often - therefore the number of reviews) a document has been through.

Issuing drafts

One of the most important points to bear in mind when issuing drafts for review, is that a draft is more of a straw-man: it is intended to be pulled apart. You should not, therefore, take it personally when your draft is returned obliterated by red ink, looking as though the only thing retained is the spaces between the words. As mentioned above, it is much better that this feedback is received at the draft stage rather than when the document has already been finalized.

Related to this, you should be wary of producing a draft that is too close to the final 'camera-ready copy', as this may deter reviewers from making changes to it (and, believe it or not, we do actually want to encourage reviewers to make changes).

That said, it is also important to stress to the reviewers that the document is a draft. It is also worth laying out what is expected of the reviewers. For example, if the reviewer is the Subject Matter Expert, then you may want them to confine their review to the technical content of the document. In this case you should make clear that you do not expect them to identify (for example) formatting inconsistencies, suggestions on layout, or grammatical errors. You may need to assure them that these things will be identified and corrected later by someone else (even if that is yourself) but they should appreciate the fact that they are not required to perform this level of review themselves.

To this end, it is often worthwhile issuing a `Guidelines for Reviewers' document, clearly outlining what they should be checking for and what they can ignore. If different reviewers are responsible for checking different things, then you may want to consider developing one set of guidelines per reviewer.

If you send out drafts for review, consider tracking them, and work out how to recall/replace them when the final document is published.

Personal tools
Support