Establishing project requirements

After you have assessed candidate technical writers for general suitability, you will need to discuss with them the specifics of your requirement. This will help you to identify the most suitable technical writer for your documentation project.

This page suggests some topics you should discuss. Do not expect to obtain final answers to all the questions — some will probably need further investigation, possibly as part of the project itself. Questions to consider include:

  1. What documents do we need?
  2. Printed documents or screen documents?
  3. Writing, rewriting, or editing?
  4. Which publishing tools should we use?
  5. Will the documents be translated?
  6. How do we specify the work?
  7. Who is responsible for what?

What documents do we need?

You might even start from one question further back: do you need any documents? Sometimes you will not. One example is when all users are trained on the product or process. Another is when users have experience on a similar product: if they can drive one car, they won't need a manual to tell them how to drive another, although they might appreciate a quick reference guide to identify any special features. Publish only enough information to meet the readers' needs and no more.

When you consider what documentation you need, be sure to understand the goals and objectives of the development project. Define the goals and objectives for the publications project so that they are aligned with the development project.

Before you make final decisions about the documentation, think about the background to the development project. Use this to compose a statement of the goals for the documentation (which should align with the goals of the development project). These will be influenced by the audience and the task to be done. The information needed to plan documents is not identical to that needed to design products.

With your help, the technical writer will analyse the audience and the tasks that they perform.

Together, you will consider the general document design.

Printed documents or screen documents?

In some sectors, notably information technology, modern media of various kinds have replaced printed documents. At a simple level, documents can be delivered as PDF (Portable Document Format) files: this transfers the cost of printing and distribution to the users, which can be convenient but should not be taken for granted. User assistance for software packages is often embedded into the product in the form of online help. This may follow a similar structure to a printed manual or it may be context-sensitive, taking readers directly to information related to the product feature from which they accessed the help. At a more advanced level, interactive manuals can integrate demonstrations, tutorials and simulations to provide training as well as instructions.

Electronic formats provide many benefits, from better search facilities to more varied presentation styles.

However, printed manuals can be easier to read than online documents, especially where long descriptions are involved. They confer a degree of perceived value to products, which can be particularly useful for software packages where purchasers receive no physical product for their money. A particular example where print is better than online formats is for installation and troubleshooting instructions, where the product is not yet running, or has ceased to run, and so the user is unlikely to be able to access embedded assistance.

Discuss the issues with your technical writer and choose an appropriate medium for the project.

Writing, rewriting, or editing?

Consider whether you are asking the technical writer to write, rewrite or edit your documentation. The boundaries between these activities are not distinct: a writer producing new documents may spend much time rewriting and editing material from other sources, whether taken from specifications or provided by subject-matter experts. Generally, it will take longer for a technical writer to create new documents than to rewrite or edit existing documents.

Rewriting is really another name for extensive editing. There is a model for the different ways in which documents can be edited, which are described as levels of edit. If your documentation requires changes at several of these levels, the writer will effectively need to rewrite some or all of the text. This may take almost as much time as writing a new document.

Which publishing tools should we use?

Your company policy may dictate the choice of tools. However, if you are in a position to select the tools for a project, choose carefully to optimise quality and productivity. Your technical writer should give you guidance on the most suitable tools for the project.

Using existing desktop software can be tempting, because it reduces costs and dependency on specialist skills. However, tools designed particularly for certain types of documentation provide features that save time and make it easy to include special documentation elements. Consider two factors when you approach tool selection:

For different types of projects, consider different tools:

The latest trend in large documentation projects is to use XML-based publishing techniques. Advantages include easy reuse of content for different documents or media, independence of proprietary formats and a range of commercial and open source tools. However, unless your organisation is already using this technology, it is unlikely to be cost-effective for a single project done by one or two writers.

You may also need a graphics tool. There are two categories of graphics:

Whatever your choice, it's better to establish the preferred tool at the start of a project than to ask a writer to change later.

Will the documents be translated?

Translation continues to become more important as business grows ever more global. The whole industry is now described by an acronym, GILT:

Technical writers need to know the audience for whom they are writing. Technical writing should always be clear and concise, but specific controls over language or content may be appropriate for use in particular countries or for source material to be translated.

How do we specify the work?

Two aspects to consider are the overall specification (project plan) and the content specification (documentation plan). These might be part of a single document, or they might be separate. The specification for the work is likely to be the outcome of a joint investigation by your team and the technical writer.

Determining the best way to tackle the project is one of the most difficult aspects: writing content to slot into the chosen structure is the most visible but sometimes the least difficult task. Up to ten per cent of the total project time might be needed for planning, so a detailed plan might be the first chargeable deliverable.

Who is responsible for what?

Make sure that your agreement defines the rights and responsibilities associated with the documentation. Two important aspects are:

If milestones depend on information or test systems being available, define clearly who must do what by when. Specify what the writer is expected to do if the required input does not arrive: how will failures be escalated and how will any costs be apportioned?

Your experts will review the content of documents but who will copyedit the text? In a publications department, it's common for colleagues to peer review one another's work — do you need an editor as well as a technical writer?

Checking of documents often stops at reviews by subject-matter experts, business experts and representatives of the user community. Particularly for instructions, two further stages of testing should be considered:

Think ahead when you assign responsibilities. How long is the documentation likely to be in service? What changes do you foresee and who will make them?

As well as defining the technical requirements of your project and deliverables, specify what administrative tasks will be required and who will do them. What procedures, standards and terms of business will the writer need to follow? What forms, timesheets, progress reports and invoices will the technical writer need to submit?

Once you have established your requirements and commissioned a technical writer to work on the documentation project, you will be ready to work with your technical writer. As the project progresses, you may of course need to revise your initial requirements and plans.

Sponsored by TechScribe technical writing