20 Years of
Technical Writing
Joaquim Baptista
ISDOC’14
Lisboa
Portugal
17-May-2014
Why Start a
Technical Writing Department?
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 2
English translation...
Major points, after 20 years
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 3
Learn before writing. “Clear tho...
(Learning) Operations
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 4
Unique concepts.
Business variation.
Op...
(Learning) Systems
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 5
21 services.
26 applications.
6 telephony ...
(Learning) Telephony Gateways
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 6
... varies with switch.
... var...
(Learning) Scripting
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 7
Proprietary language
with unique concept...
(Learning)
Curriculum Development
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 8
Chunking.
Hands-on
exercise...
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.
Subvers...
Hiring Tecnhical Writers
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 11
CV
Test
Interview
Newspapers. Recru...
Training Technical Writers
17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 12
101 book,
product
training
Coachi...
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).
• Technica...
Upcoming SlideShare
Loading in …5
×

20 Years of Technical Writing at Altitude Software

385 views

Published on

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.

Published in: Design, Business
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
385
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
6
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

20 Years of Technical Writing at Altitude Software

  1. 1. 20 Years of Technical Writing Joaquim Baptista ISDOC’14 Lisboa Portugal 17-May-2014
  2. 2. 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?
  3. 3. 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.
  4. 4. (Learning) Operations 17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 4 Unique concepts. Business variation. Operational implications of technical decisions.
  5. 5. (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.
  6. 6. (Learning) Telephony Gateways 17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 6 ... varies with switch. ... varies with switch configuration. Unified telephony model, but...
  7. 7. (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.
  8. 8. (Learning) Curriculum Development 17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 8 Chunking. Hands-on exercises.
  9. 9. Learning to Illustrate 17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 9 Patrícia Magrinho
  10. 10. 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.
  11. 11. 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?
  12. 12. Training Technical Writers 17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 12 101 book, product training Coaching Expert books? 1 Year 25% 2 Years 25% 3 Years 17% 33%
  13. 13. People and Innovation 17-May-2014© Altitude Software, ISDOC’14, Lisboa, Portugal 13
  14. 14. 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

×