20 Years of Technical Writing at Altitude Software
-
Upload
joaquim-baptista -
Category
Design
-
view
74 -
download
0
description
Transcript of 20 Years of Technical Writing at Altitude Software
20 Years of
Technical Writing
Joaquim Baptista
ISDOC’14Lisboa
Portugal17-May-2014
Why Start a
Technical Writing Department?
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 2
English translation of
developer Portuguese?
Expensive, outdated,
outsourced documentation?
Major points, after 20 years
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 3
Learn before writing. “Clear thoughts in clear words.”
Then, learn better, write better.
No formal training on
technical writing.
1. Hire English, wits.
2. Train on product.
3. Train on writing.
4. Innovate.
(Learning) Operations
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 4
Unique concepts.
Business variation.
Operational implications
of technical decisions.
(Learning) Systems
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 5
21 services.
26 applications.
6 telephony gateways.
..... 1000 small parameters.
Also, third-party systems.
(Learning) Telephony Gateways
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 6
... varies with switch.
... varies with switch configuration.
Unified telephony model, but...
(Learning) Scripting
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 7
Proprietary language
with unique concepts.
(or your choice of language)
Several worlds to coordinate.
Specific roles to fulfill.
(Learning)
Curriculum Development
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 8
Chunking.
Hands-on
exercises.
Learning to Illustrate
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 9
Patrícia
Magrinho
Effective Tools
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 10
DITA Open Toolkit.
Serna XML Editor.
Subversion, Unix tools.
Scripts to generate topics.
1360k words.
6800 topics.
1075 slides.
3800 images.
170 maps.
Hiring Tecnhical Writers
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 11
CV
Test
Interview
Newspapers. Recruiters. Recommendations.
English. Technically minded. Phone call?
Write procedure. Rewrite confusion.
Change program?
Whole team.
Writing samples? Additional test?
Training Technical Writers
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 12
101 book,
product
training
CoachingExpert books?
1 Year
25%
2 Years
25%
3 Years
17%
33%
People and Innovation
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 13
Summary
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 14
Professional learners (not just writers).
• Technical writing (for lack of formal training).
• Product (unique, vast).
• Audience background (several of them).
What has helped?
• Audience profiles.
• Improved training.
• Writing patterns.
“Everything is hard until someone makes it easy.” – xkcd.com/1349