Writing case study: IBM hardware service training

This page outlines a real writing project I completed at IBM. This hardware service training content was used internationally by hundreds of service engineers to learn about this new IBM system.

Back to Skills

Some features of this sample

A well-defined audience: the course defines its users, IBM hardware service representatives worldwide, before anything else
Clear objectives: every topic states what the learner will be able to do, and checkpoint questions measure it
Style guide consistency: this content looks and feels like all other IBM content because it follows the IBM Style Guide
Consistent layout and structure: every topic follows the same pattern, so that learners can easily follow the flow of the document

Cover page of an IBM self-study booklet: IBM FlashSystem 5015, 5035, and 5045 Service Training, with the course code, a strip of four illustrations, and TLS Global Skills Development. — The course booklet, written and laid out in FrameMaker.

Audience, purpose and objectives first

The course description opens by defining the audience (IBM System Service Representatives worldwide), the purpose, and the objectives.

For learners: they know straight away whether the course is for them and what they will be able to do by the end.

The booklet's course description page, with headings for duration, purpose, audience, prerequisites and objectives. The audience is worldwide IBM System Service Representatives. Prerequisite course names are redacted. — The course description page.

Objectives drive the design

Each topic opens with a topic overview and its objectives. The objectives guide what each section teaches and give the checkpoint questions something to measure.

For learners: a clear target before they start, and a way to measure their own progress.

The top of the Topic 1 Overview page in the booklet. A short overview says the topic describes the key features and specifications of IBM FlashSystem 5015/5035/5045 systems, followed by three objectives: identify major hardware features, list basic system specifications, and describe the available warranty options and their related IBM service obligations. — The opening of Topic 1: an overview, then the objectives.

One new idea at a time

Topic 1 opens with a one-sentence definition. Each section then adds one idea: what the product is, what it can do, which models exist, what it looks like, and who services it.

For learners: a new and complex product, built in steps they can follow.

Diagram of the sections in Topic 1 as rising steps: 1.1 What it is, 1.2 What it can do, 1.3 Which models exist, 1.4 What it looks like, 1.5 Size, weight and power, 1.6 What can be ordered, 1.7 Who services it. — The sections of Topic 1, each adding one idea.

Written to the IBM Style Guide

Abbreviations are spelled out on first use, every list has a full-sentence introduction, cross-references give number and title, and headings use sentence case.

For learners: terms and formatting that match the rest of IBM's documentation.

Booklet page for section 1.5, Specifications, with sentence-case numbered headings, numbered table captions, a cross-reference to Table 1-6, and tables of enclosure dimensions, weights and air temperature requirements in metric with imperial in brackets. — Section 1.5: sentence-case headings, numbered tables, and cross-references.

Labelled images build familiarity

A photograph or image of each part is shown, with callouts highlighting key features.

For learners: they recognise each part and can locate relevant ports when they are working with real hardware.

Rear view of the FlashSystem 5035/5045 control enclosure with callouts naming the management, I/O and technician ports, node canisters 1 and 2, the optional host interface card (HIC), the SAS expansion ports, and power supply units 1 and 2. — Figure 1-6: rear view of the FlashSystem 5035/5045 control enclosure.

Checkpoint questions confirm learning

Every topic ends with a knowledge check about key points related to the topic objectives. Answers are in the appendix so that learners can review their progress.

For learners: confidence before they service real hardware, and a clear signal of what to review.

The Topic 1 checkpoint questions page: four multiple-choice questions on the differences between FlashSystem models, two true-or-false questions, and a pointer to the answers in Appendix A. — The Topic 1 checkpoint questions.

Back to Skills