Technical Writing

SimplifiedBy Matthew Bin – Calamus Consulting

About Matthew Bin

Graduated with B.A. in English Literature (Honours), April 1996

Began M.A. in English Literature, September 1996

Panic set in, November 1996

Became technical writer, February, 1997

Graduated with M.A. in English Literature, September 1997

Hired by Compaq Canada, September 1997

Employers and clients include Compaq, MOE, MMAH, Fidelity Investments,

Descartes Systems Group, i2 Technologies, Talent Technology Group

Well over 1 million words of paid technical writing by 2006

What is Technical Writing?

Any documentation that describes or instructs on a technical subject, device,

or product

Can include:

User manuals

Technical manuals

Reference materials

API guides

Release notes

Knowledge base articles

Configuration/setup guides

FAQs

Wikis

Web Pages

And more…

What is Good Technical Writing?

What do you think good technical writing is?

Good technical writing has qualities like…

Clarity

Completeness

Ease of reading

Ease of use

Logical organization

(What else?)

Why Technical Writing?

Adds value to your products

Adds value to your brand

Increases customer satisfaction and retention

How Do We Get There?

The Plan

The Structure

The Approach

Planning Your Document

Typically, technical documents are written the wrong way

“Once upon a time…”

The result: an unhappy ending

Planning Your Document:

How to Create Your Plan

How do you produce every single other technical product?

Research needs

Understand technical requirements

Create a specification

Why not the same for your documents?

Planning Your Document:

The Document Specification

What are we creating?

Who is it for?

Why are we creating it?

Where is it going?

What does it contain?

Structuring Your Document

Writing is not words

Writing is organizing thought

A strong structure means a strong document

Think about all the information you need to present BEFORE you start to put

it together

Structuring Your Document:

Headings

Divide your document into logical groups

Tasks

Features

Groups of users

Use Headings

Headings, sub-headings – groups and sub-groups

Structure reflects content

Don’t over-structure

The depth spiral

Don’t go too deep – three or four levels at most

Same kind of content needs to be at the same level

Structuring Your Document:

Formatting

Numbering, fonts, and other fancy stuff can help, but…

Heading numbers

Do they add anything?

Indents, text size

Can help to show organization

Fonts and formatting

VERY easy to overdo

One font for headings, one for text, one for code – THAT’S ALL

Approaching the Writing

The natural way to write about a product: describe it

Product > Feature List > Description of each feature

Users do not need this

Approaching the Writing:

What to Do Instead

What are we missing?

THE USER

From the user’s point of view:

I need to perform a task

I don’t know or care about features

I don’t care about your product – my tasks are not your tasks

Function-based or use-based approach

Approaching the Writing:

Function-based Approach

Puts the user’s needs first

Helps the user find content in the document

Helps to position the content to the user’s advantage

Minimizes excess documentation

…can improve product design!

Approaching the Writing:

Where to Start?

Start from the user’s goal

Work backwards to find the process path

Describe only one task at a time

Name the section after what the user needs to do

Approaching the Writing:

How to Proceed?

Walk through the task; describe each step

Add notes, if/thens, screen shots only if needed

Screen shots and diagrams must help the text – minimize them

Approaching the Writing:

Quality Assurance

After you’re done, follow your own instructions and try to complete the task

If it is something the user has to do to complete the steps, include it in the

text

If you do not test your own documentation…

Tech Writer Tips:

Consistency

Terminology

Use the same words for the same things (e.g. “Screen”, “Window”, “Interface” –

pick one and stick with it)

Don’t get fancy; finesse is for poets

Audience

Talk to the same person

Make the same assumptions, stay on the same level

Tech Writer Tips:

Simplicity

Simple language is best

Don’t use “please”

Stay in the present tense

Conclusion

Technical writing is about organization

Language, writing skills are not barriers to good documentation

Make a plan, and focus on the user

Questions?

Matthew Bin

Calamus Consulting

calamusconsulting.ca

info@calamusconsulting.ca