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

On the web at *** 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) 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 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 for more resources and info.

Previous by Author: Restrictions on telecommuting in other venues...
Next by Author: Conditionalized text...
Previous by Thread: RE: Software For Students (PSP v PS)
Next by Thread: RE: So you wanna be an API documentation writer? (WAS: RE: API Documentation)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads