The Technical Writing Process

The natural beginning of any project is to find out what the key stakeholders require from the project. What they are expecting and hoping to achieve. An important aspect is establishing the level of assistance available from key personnel such as Subject Matter Experts, and how much time they can give to the project.

It is important to identify the end-user at the very start, so the documentation can be written to the correct level. A skilled engineer will need a different level of detail to a member of the public.

The complexity of the subject must also be considered. Complex procedures will often require breaking down into smaller procedures, different writing methods may be necessary to help make the instruction clear.

Presentation of information needs to be considered carefully, ensuring it is easy to access and absorb in often frustrating or pressured situations.

For many technical writers, writing documentation really begins when they first get sight of the source information. Commonly this is made up of an existing manual, engineer’s notes, design drawings, audit reports, maintenance proceeds or a list of reported problems that documentation can help resolve. For software documentation, writers are often given access to the software, therefore can generate information independently reducing the information gaps.

Identifying and closing the gaps in information is a critical task in producing technical documentation. This is where using in-house staff is a huge weakness, as they simple won’t know what is missing. Experienced technical writers quickly identify what is needed to form the right level of document. 

The gap analysis naturally produces a List of Required Information, that the technical writer can provide to the SME’s to source. Alternatively, the writer may visit site to gather further source through taking photos, product demos, walkthroughs and interviews.

The outline structure of the manual will variably be begun at different stages by different writers. Commonly a typical structure and layout template already exists, or is dictated by a particular type of document. Sometimes this will be performed earlier and used to help  show where further information is required as part of the gap analysis. Clients may have an existing style they wish to incorporate, or an example they wish to replicate, alternatively a bespoke style can be created. Planning is required to consider where information will fit within the document, how it will be incorporated, displayed and accessed. And how the document will be used.

Preparing source information involves splitting existing paragraphs of information in to distinct “packets” of information. An example of a poorly written paragraph is where there is a mix of different types of information, such as procedures interspersed within a description of a product, or installation mixed with maintenance instructions.

The writing or editing of packets into clear English is a key requirement for an end user to understand a concept easily and therefore carry out a task successfully.

Some projects require a specific type of categorisation. For example software applications describing the functions and use of the software may include category types such as:

• Description
• Procedure
• Screenshot

Source information needs splitting and edited or written to these specific category types, so information within a packet contains information of one specific packet type.

Once the List of Required Information is complete as much as possible, source information exhausted and categorised and the document planned, a draft documentation will be generated for client review. Writers will clearly identify within the draft document where they need further information, for example more details of operation or maintenance tasks. At this point writers need the critical assistance of subject matter experts to provide their expert knowledge on specific tasks.

This is often in the form of a review and comment process of the draft documentation. The client will provide general feedback, the SME’s will clarify technical processes and the writer will incorporate all of this information into the documentation one last time. The review process may be repeated more than once.

The finishing touches happen at this late stage. When documentation will be formatted to an agreed stylesheet, checked for consistency, have vital navigation applied, page layout applied and a thorough check for language use.

At this point the documentation takes on a truly professional feel which sets it apart from documentation written by an unskilled hand.

All documentation we are asked to develop originally written by non-authors, suffer from a high level of inconsistency. This is something we can easily eliminate through use of our professional tools and custom developed stylesheets which are made unique to each customer.

The final stage is to output the documentation in the desired format.

This is typically a html format for online use, or a PDF format which can be easily accessed through many devices. PDFs are normally structured for 2-sided print to save on resources whenever printed and to work with online viewers. There are other formats but they are usually a manipulation of these two.

Printed hardcopies can be arranged where needed. From a simple stapled booklet, a bound manual to a card covered glossy brochure.