what can your technical writer do? an acs wa branch presentation july 2008 stephanie bateman-graham...

What can your technical writer do?

An ACS WA branch

presentation

July 2008

Stephanie Bateman-Graham MACS PCP

What Can Your Technical Writer Do?2

SBG

Stephanie Bateman-Graham

1993 BA (Hons) Psychology, UWA Thesis “System Response Time and User

Performance in Data Entry” Centre for Computer Managed Training and Decision

Support Systems (COMTADSS) 2001 ACS Associate Member 2003 ACS Certification Program (Project

Management), regraded to Member Currently contracting to XempleX Pty Ltd as a

writer/analyst.


SBG

Introduction

Why are we here? What is a technical writer? How do they add value? How do you find them? How do you look after them?


SBG

Disclaimer

Stereotypes are useful, but are not an indicator of individual behaviour.

A composite view. Judge individuals on their merits.


SBG

Overview

Part I: What is a technical writer? Part II: How do they do it? Part III: Selection, Care and Feeding


SBG

Scenario

It doesn’t do what we wantIt doesn’t do what we needIt doesn’t do anything at allHelp doesn’tI hate itI can’t do my jobIt smells funnyThe consultant smells funny

The new system is perfect…

but the users complain:


SBG

A user


SBG

You are all individuals


SBG

Part I: What is a technical writer?

Part I: What is a technical communicator?

Part I: What is a technical and business communicator?

Part I: What is a technical and business and community communicator?


SBG

Typical Career Path


SBG

Generalist or specialist?

Swiss army knife Software manual writer


SBG

BusySmallWidgetCo

CEO

Developer(s)/IT Support/

Product Support/Consulting

Tester?

CTO Marketing/

Finance

Admin


SBG

BusySmallWidgetCo

CEO

Developer(s)

Tester

Admin

CTO

Marketing/Finance

Value-Added Reseller

Trainer

Support

Business Analyst

Project Manager

GUI Designer

Technical Writer


SBG

Technical Writer, and silver bullet?

Business analyst Project manager GUI designer Company secretary Researcher Editor Web designer Tester Diplomat Requirements analyst Indexer Data modeller User advocate

Animator Team leader Localisation manager Usability expert Graphic designer Web developer Illustrator Knowledge manager Trainer Marketing expert Curriculum developer Database administrator Caped crusader


SBG

Specialist roles

Design and Development Sales and Marketing Deployment End-user


SBG

Specialist: Design and development

Use Cases Requirements Enhancement requests Design documents Program text (e.g. labels, menus, error messages)

Test specifications Bug reports


SBG

Specialist: Sales and Marketing

Brochures Fact Sheets E-mail contact templates Web content White papers Product presentations

– PowerPoint– Animations– Film voiceover scripts

Reseller’s guide


SBG

Reseller’s Guide

Style guide for marketing messages Product and industry background Product features Quotation process Pricing


SBG

Specialist: Deployment

Change plans User education program Installation and configuration instructions Trainer-led training materials Support desk guides


SBG

Configuration guidelines

Consultant’s guide Map client business policy to product

technical system settings.


SBG

Policy >> Configuration

ClientConsultant

System Administrator

User

Describes policy

Translates policy to

configuration

Does configuration

Uses system

Prompts for policy

Trainer

Delivers training


SBG

Training materials

Curriculum Presentations Exercises Data Handouts Tests Certificates Student Guide: What to learn Trainer’s Guide: How to teach it


SBG

“Tech writers write software manuals”


SBG

Specialist: End user documentation

Glossary Index Goal-oriented user

guides Function-oriented

reference material Problem-oriented

troubleshooting guides

User Guides:– Install/Upgrade– Quick Start – Job-defined

Administrator Data entry Supervisor Sales

Self-paced training– Simulation-based– e-Learning


SBG

Where is the value?

Concept Development Sales Deployment Support


SBG

Efficiency

Organise information for busy people Fast access Templates


SBG

Consistency

Glossary of terms Similar widgets/processes for similar tasks Naming controls, commands Editing for consistent voice Templates


SBG

Acceptance

Understand the customer’s perspective and business needs. Answer this question:

“How can this tool help me to achieve my business goals?”

This is mere curiosity:

“What does this bit do? What happens when I press this button?”


SBG

Part II: How do they do it?

Listen Learn Plan Ask Challenge Do Translate Write Draw Test Revise


SBG

Listen


SBG

Learn


SBG

Ask

Is it supposed to

do that?


SBG

Do


SBG

Translate

Foreign language <=> Local language

Local dialect <=> Audience language

Technical language <=> Common language

Business language <=> Technical language

Business goals <=> Technical goals

Use cases <=> Functions

Words <=> Images


SBG

Logic

Value Q is derived from values R and S These nouns go with these verbs A is a precursor to B Person X must complete Task Y with data Z


SBG

Brief words of wisdom

Complex language does not make you look clever

Plain English is not an insult to the reader Consistent grammar, usage Controlled vocabulary


SBG

KISS

Elaborate linguistic structures absorb the reader’s cognitive capacity at the expense of their understanding of the subject matter.

Complex writing is distracting.


SBG

KISS

“Genius is the ability to reduce the complicated to the simple” – C. W. Ceram

“Do not accustom yourself to use big words for little matters” – Samuel Johnson

“The most valuable of talents is that of never using two words when one will do”– Thomas Jefferson

“Easy reading is damn hard writing” – Nathaniel Hawthorne


SBG

Please don’t try this at home

“THE EXCLUSIVE FOCUS ON UNIVERSAL PRINCIPLES AND STRONG NEGATIVE OBLIGATIONS DREW THE SPATIO-TEMPORALLY EGALITARIAN INTERPRETATION OF THE KERNEL OF THE NOTION OF SUSTAINABLE DEVELOPMENT TO THE SAME PREOCCUPATION WITH THE SURVIVAL OF THE HUMAN SPECIES THAT CHARACTERISES THE APOCALYPTIC VIEWS OF RADICAL ENVIRONMENTALISTS.”

Beekman, Volkert (2004), 'Sustainable development and future generations', Journal of Agricultural and Environmental Ethics, 17 (1), 3-22. Page 12.


SBG

Humour

Must have a sense of humour Must be able to restrain sense of humour


SBG

Contact with colleagues

Tech writer lists Professional associations Conferences/seminars/workshops Local groups


SBG

Part III: Selection, Care and Feeding


SBG

An investment

What is the project scale and requirements? What resources does the project need? How much work can one person do?

Small organisations – generalist Large organisation/project – specialist


SBG

Qualifications

Be able to write. Have research skills Understand the writing process Have empathy, imagination, curiosity,

attention to detail, learning ability, intelligence, problem solving ability, common sense...


SBG

Don’t laugh, it happened to me

…and every single technical writer I’ve ever spoken to.


SBG

Team player, leader or hermit?

Naturally team players Often required to be independent Good organiser, good negotiator Good manager?


SBG

Experience

ESSENTIAL: Minimum 2 years experience with HelpGadget v4.0, Office 2007, SAP and Oracle

(Please) don’t select rigidly on the basis of experience with a particular tool, product or industry

Look at broader experience Assess the portfolio


SBG

No experience desired

Experts make the worst teachers Novices require explicit information first Intermediate students may have to break bad

habits


SBG

Novice to Expert

Novice Intermediate Expert

Training Experience

Transition errors

“Beginner’s luck”

“Intuition”

Implicit Knowledge (Ideas)

Explicit Knowledge (Rules)


SBG

Feedback

Editing Proofing

– Accuracy– Readability– Legal– Press

Acceptance testing


SBG

Cracking the whip

Technical Writers like to be productive. Let them. Balance organisational tasks with

creative/content production tasks.


SBG

The Next-Generation Product Documentation Report:

Getting Past the “Throw It over the Wall” Approach

[The technical communicator is] the hub for information about a manufacturer's product [and] should be leveraged throughout the entire organization. . . .

The end result will be a more consistent and positive product information experience for end users at every customer touch point.

Aberdeen Group, December 2006.


SBG

Conclusion

Technical Writing is a profession Consider investing a senior technical writer

as a generalist in a small organisation Give them information and feedback Don’t spread them too thin. Choose the right one Let them do their thing


SBG

Contact

Stephanie Bateman-Graham

[email protected]

0402 712 344

what can your technical writer do? an acs wa branch presentation july 2008 stephanie bateman-graham...

Documents

technical communicator

business communicator

sbgspecialist rolesdesign

needit doesnt

wantit doesnt

sbgscenarioit doesnt

community communicator

acs wa branch presentationjuly