TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
So you wanna be an API documentation writer? (WAS: RE: API Documentation)
Subject:So you wanna be an API documentation writer? (WAS: RE: API Documentation) From:Berk/Devlin <armadill -at- earthlink -dot- net> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Sat, 24 Feb 2001 03:34:24 -0800
I have been documenting APIs for about 5 years now. For many years before
that, I was a C and then a C++ developer.
When I was a programmer, people would tell me that they were "taking an
introductory programming course" in anticipation of becoming programmers
and making an easy fortune. I actually had people tell me they were
enrolling their CHILDREN in programming classes so they could make their
Very few of these people ever even completed their first course; they
were shocked at all the attention to detail that programming
requires. "Sheesh," they'd tell me. "This is grunt-work. This is what
computers ought to be doing."
Lately, the types of folks for whom programming proved too difficult seem
to be looking at documenting APIs as the way to make an easy fortune.
Well, I'm sure there are those out there who will go on to be happy and
successful API writers as I am.
As my contribution to the effort, here is my proposed curriculum for an
on-line course I am not planning to teach, called "API-Writing 101". (I'm
happy to license this course, if anyone is interested...)
Prerequisites: Access to a computer and text editor/documentation tool and
know how to use them. Have ability to write clearly in your native
language and to use a spell-checker. Have ability to communicate through
speech, telephone, fax, and email. Know what "Hello World" really means
or, better yet, have the ability to figure this out without asking on
Week 1: Read "Soul of a New Machine". If you have not heard of this book,
read it twice. If you have already read it, read it again. This book was
written 30 years ago and the lives of engineers have only gotten
worse. Not only that, but the book is extremely well-written, so it should
appeal to your aesthetic side as well.
Week 2 (well, maybe season 2): Enroll in a really and truly programming
complex enough. PHP maybe.
Get an A in the course. Or, an A+. No cheating now. Programming is
really easy guys. But just as not everyone can sing opera and not everyone
can draw and not everyone can play basketball well, not everyone has an
aptitude for programming. If you cannot get an A in one, simple,
introductory HANDS-ON programming course, do NOT go on to the next step.
Week 3 Re-read Soul of a New Machine. It's well-written and it describes
the lives of the folks upon whom you will be staking your livelihood.
Week 4 Reflect again. Make sure you are willing to work until all hours
with a group of extremely terse smart guys and a few nerdy girls who
subsist on Jolt Cola and rarely step out into the sunlight and have the
social graces of cats and are half your age and make twice what you do and
drive very nice cars and some of them do not shower regularly. (Yes, this
may seem stereotypical, but it's based in reality.)
Week 5 Congratulations. You are now an API documentation writer. Welcome
to my world. Put all these skills on your resume and apply. The world is
your oyster. (If you believe this last, I know of some choice farmland in
On the web at www.armadillosoft.com *** Armadillo Associates, Inc.
~ Project management, developer relations and
extremely-technical technical documentation that developers find useful.~
Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17) http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.
Sponsored by ForeFront, Inc., maker of ForeHelp Help authoring tools
for print, WinHelp, HTML Help, JavaHelp, and cross-platform InterHelp
See www.forehelp.com for more information and free evaluation downloads
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.