View
74
Download
0
Category
Preview:
DESCRIPTION
Presented at ISDOC'14, with drawings by Patrícia Magrinho. Presentations by local technical writers have shown a surprising diversity of writing and content governance scenarios on mature software companies. Mature companies have unique business problems that require unique technical and human solutions. On Altitude Software, writers struggle to control the complexity created by the organic growth of a mature software suite. As a response, feature-based documentation was rewritten in 2003 as task-based documentation, and is being rewritten again since 2010 into custom topic patterns. Over time, Altitude Software learned to hire and train highly technical writers. Technical writers in Altitude Software became professional learners that must learn specific writing techniques, become experts in the product, and approach the background expertise of specific user audiences.
Citation preview
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
Recommended