Effective technical writing

A one-, two-, or three-day training workshop

The aim of this programme is to help attendees create better quality technical documents in an organised and efficient manner. It will give those new to the topic an appreciation of how to approach the task professionally whilst those with more experience will be able to refresh and refine their skills.

The programme comprises three complementary one-day modules:

Module 1: Essential skills for technical writers

Module 2: Creating better specifications

Module 3: Writing better technical reports

The programme presents a structured methodology for creating technical documents and provides a range of practical techniques that help delegates put principles into practice. Although not essential, it is strongly advised that delegates for modules 2 and 3 have already attended module 1, or another equivalent course.

Who should attend?

This course is designed to help those involved in creating technical documents such as reports, manuals, specifications and user guides.

Format

Each module comprises a mix of tutorials and practical case study sessions geared to the client’s business environment.

Special features

The three modules in this programme can be taken as stand-alone workshops or in any combination to create a 1-, 2-, or 3-day programme.

Expert trainer

John is an independent consultant specialising in project and change management. He established his consultancy practice in 1990, following 20 years of industrial management experience, and provides clients with a wide range of project management and team development programmes. He also provides facilitation and consultancy services to help clients deal with current issues or to assist in developing management practices and procedures.

Session outline

Note: the content of each module as shown here is purely indicative and can be adapted to suit your particular requirements.

MODULE 1: ESSENTIAL SKILLS FOR TECHNICAL WRITERS

1. Introduction to the programme

2. Creating effective technical documents

What is technical writing? How does it differ from other writing?
Key qualities of an effective technical document
Communication essentials and the challenges faced by technical writers
The lessons of experience: how the best writers write
The five key steps: prepare – organise – write – edit – release (POWER)

3. Preparing to write

Defining the document aims and objectives; choosing the title
Understanding technical readers and their needs
Getting organised; planning and managing the process
Integrating technical and commercial elements
The role of intellectual property rights (IPR) e.g. copyright

4. Organising the content

The vital role of structure in technical documents
Deciding what to include and how to organise the information
Categorising information: introductory, key and supporting
Tools and techniques for scoping and structuring the document
Creating and using document templates – pro’s and con’s

5. Writing the document

Avoiding ‘blinding them with science’: the qualities of clear writing
Problem words and words that confuse; building and using a glossary
Using sentence structure and punctuation to best effect
Understanding the impact of style, format and appearance
Avoiding common causes of ambiguity; being concise and ensuring clarity
Using diagrams and other graphics; avoiding potential pitfalls

6. Editing and releasing the document

MODULE 2: CREATING BETTER SPECIFICATIONS

1. Introduction

2. Creating better specifications

The role and characteristics of an effective specification
Specifications and contracts; the legal role of specifications
Deciding how to specify; understanding functional and design requirements
Developing the specification design; applying the principles of BS 7373
Getting organised: the key stages in compiling an effective specification

3. Preparing to write a specification

Defining the scope of the specification; deciding what to include and what not
Scoping techniques: scope maps, check lists, structured brainstorming
The why / what / how pyramid; establishing and understanding requirements
Clarifying priorities; separating needs and desires: the MoSCoW method
Useful quantitative techniques: cost benefit analysis, QFD, Pareto analysis
Dealing with requirements that are difficult to quantify

4. Organising the content

The role of structure in specifications
Typical contents and layout for a specification
What goes where: introductory, key and supporting sections
Creating and using model forms: the sections and sub sections
Detailed contents of each sub-section
Exercise: applying the tools and techniques

5. Writing the specification

Identifying and understanding the specification reader
Key words: will, shall, must; building and using a glossary
Writing performance targets that are clear and unambiguous
Choosing and using graphics
Exercise: writing a specification

6. Editing and releasing the document

MODULE 3: WRITING BETTER REPORTS

1. Introduction

2. Creating better reports

What is a technical report? Types and formats of report
The role and characteristics of an effective technical report
Understanding technical report readers and their needs
The commercial role and impact of technical reports
Getting organised: the key stages in compiling a technical report

3. Preparing to write reports

Agreeing the terms of reference; defining aims and objectives
Being clear about constraints; defining what is not to be included
Legal aspects and intellectual property rights (IPR) for reports
Preparing the ground; gathering information and reference documents
Keeping track of information: note making, cataloguing and cross referencing
Tools and techniques for developing a valid and convincing argument

4. Organising the content

The role of structure reviewed; some typical report structures
Who needs what: identifying the varied needs of the readership
What goes where: introductory, key and supporting sections
Creating and using model forms: the sections and sub sections
Detailed contents of each sub-section
Exercise: applying the tools and techniques

5. Writing the report

Planning the storyline: the report as a journey in understanding
Recognising assumptions about the reader; what they do and don’t know
Converting complex concepts into understandable statements
Presenting technical data and its analysis; the role of graphics
Presenting the case simply whilst maintaining technical integrity
Exercise: writing a technical report