What can your technical writer do? An ACS WA branch presentation July 2008 Stephanie Bateman-Graham...
-
Upload
lilian-carr -
Category
Documents
-
view
218 -
download
0
Transcript of 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.
What Can Your Technical Writer Do?3
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?
What Can Your Technical Writer Do?4
SBG
Disclaimer
Stereotypes are useful, but are not an indicator of individual behaviour.
A composite view. Judge individuals on their merits.
What Can Your Technical Writer Do?5
SBG
Overview
Part I: What is a technical writer? Part II: How do they do it? Part III: Selection, Care and Feeding
What Can Your Technical Writer Do?6
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:
What Can Your Technical Writer Do?7
SBG
A user
What Can Your Technical Writer Do?8
SBG
You are all individuals
What Can Your Technical Writer Do?9
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?
What Can Your Technical Writer Do?10
SBG
Typical Career Path
What Can Your Technical Writer Do?11
SBG
Generalist or specialist?
Swiss army knife Software manual writer
What Can Your Technical Writer Do?12
SBG
BusySmallWidgetCo
CEO
Developer(s)/IT Support/
Product Support/Consulting
Tester?
CTO Marketing/
Finance
Admin
What Can Your Technical Writer Do?13
SBG
BusySmallWidgetCo
CEO
Developer(s)
Tester
Admin
CTO
Marketing/Finance
Value-Added Reseller
Trainer
Support
Business Analyst
Project Manager
GUI Designer
Technical Writer
What Can Your Technical Writer Do?14
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
What Can Your Technical Writer Do?15
SBG
Specialist roles
Design and Development Sales and Marketing Deployment End-user
What Can Your Technical Writer Do?16
SBG
Specialist: Design and development
Use Cases Requirements Enhancement requests Design documents Program text (e.g. labels, menus, error messages)
Test specifications Bug reports
What Can Your Technical Writer Do?17
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
What Can Your Technical Writer Do?18
SBG
Reseller’s Guide
Style guide for marketing messages Product and industry background Product features Quotation process Pricing
What Can Your Technical Writer Do?19
SBG
Specialist: Deployment
Change plans User education program Installation and configuration instructions Trainer-led training materials Support desk guides
What Can Your Technical Writer Do?20
SBG
Configuration guidelines
Consultant’s guide Map client business policy to product
technical system settings.
What Can Your Technical Writer Do?21
SBG
Policy >> Configuration
ClientConsultant
System Administrator
User
Describes policy
Translates policy to
configuration
Does configuration
Uses system
Prompts for policy
Trainer
Delivers training
What Can Your Technical Writer Do?22
SBG
Training materials
Curriculum Presentations Exercises Data Handouts Tests Certificates Student Guide: What to learn Trainer’s Guide: How to teach it
What Can Your Technical Writer Do?23
SBG
“Tech writers write software manuals”
What Can Your Technical Writer Do?24
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
What Can Your Technical Writer Do?25
SBG
Where is the value?
Concept Development Sales Deployment Support
What Can Your Technical Writer Do?26
SBG
Efficiency
Organise information for busy people Fast access Templates
What Can Your Technical Writer Do?27
SBG
Consistency
Glossary of terms Similar widgets/processes for similar tasks Naming controls, commands Editing for consistent voice Templates
What Can Your Technical Writer Do?28
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?”
What Can Your Technical Writer Do?29
SBG
Part II: How do they do it?
Listen Learn Plan Ask Challenge Do Translate Write Draw Test Revise
What Can Your Technical Writer Do?30
SBG
Listen
What Can Your Technical Writer Do?31
SBG
Learn
What Can Your Technical Writer Do?32
SBG
Ask
Is it supposed to
do that?
What Can Your Technical Writer Do?33
SBG
Do
What Can Your Technical Writer Do?34
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
What Can Your Technical Writer Do?35
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
What Can Your Technical Writer Do?36
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
What Can Your Technical Writer Do?37
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.
What Can Your Technical Writer Do?38
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
What Can Your Technical Writer Do?39
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.
What Can Your Technical Writer Do?40
SBG
Humour
Must have a sense of humour Must be able to restrain sense of humour
What Can Your Technical Writer Do?41
SBG
Contact with colleagues
Tech writer lists Professional associations Conferences/seminars/workshops Local groups
What Can Your Technical Writer Do?42
SBG
Part III: Selection, Care and Feeding
What Can Your Technical Writer Do?43
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
What Can Your Technical Writer Do?44
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...
What Can Your Technical Writer Do?45
SBG
Don’t laugh, it happened to me
…and every single technical writer I’ve ever spoken to.
What Can Your Technical Writer Do?46
SBG
Team player, leader or hermit?
Naturally team players Often required to be independent Good organiser, good negotiator Good manager?
What Can Your Technical Writer Do?47
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
What Can Your Technical Writer Do?48
SBG
No experience desired
Experts make the worst teachers Novices require explicit information first Intermediate students may have to break bad
habits
What Can Your Technical Writer Do?49
SBG
Novice to Expert
Novice Intermediate Expert
Training Experience
Transition errors
“Beginner’s luck”
“Intuition”
Implicit Knowledge (Ideas)
Explicit Knowledge (Rules)
What Can Your Technical Writer Do?50
SBG
Feedback
Editing Proofing
– Accuracy– Readability– Legal– Press
Acceptance testing
What Can Your Technical Writer Do?51
SBG
Cracking the whip
Technical Writers like to be productive. Let them. Balance organisational tasks with
creative/content production tasks.
What Can Your Technical Writer Do?52
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.
What Can Your Technical Writer Do?53
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
What Can Your Technical Writer Do?54
SBG
Contact
Stephanie Bateman-Graham
0402 712 344