So you wanna be an API documentation writer? (WAS: RE: API Documentation)

[Berk/Devlin <armadill -at- earthlink -dot- net>]

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 
fortune.

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 
techwr-l.

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 
course.  Java, C, C++, Pascal.  Not HTML.  Not JavaScript.  They are not 
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 
the Sahara...)

--Emily
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.