Re: FWD: How much experience for API Writing?

[Jan Henning <henning -at- r-l -dot- de>]

>But
>mostly, I'm interested in how much programming skill a API writer needs. Is
>it enough to read code and know the keywords or do I need an in-depth
>knowledge of the programming language?

IMHO, to write _good_ documentation about an API, you should be able to
write a program using that API. Since 'writing a program' is a bit
ambiguous, let me clarify:

- You should be able to write a program that correctly uses any given API
call (and any given parameter of the call),

- you should be able to debug the program,

- you do not need to be able to write the tightest, fastest, or most
elegant code - just something that works.

If you think that this is a tall order, consider this: For writing
anything (even fiction) well, you need to know you audience. In this
case, your audience are professional programmers. If you cannot put
yourself in their shoes, you have little hope in presenting the
information just as they need it.

An analog might be learning a foreign language and writing for
foreigners: Just because you speak French, it doesn't mean that you could
write a good travel guide to the US for the French market. You need to
have lived in France to know that you need to warn your readers about the
inavailabilty of decent bread outside big citites, the intolerance of
Americans against smoking etc. (Or you need have to assimilated the
culture in a different way, although none really comes to mind.)

Hope this helps
Jan Henning

--------------------------------------------------------------------
Jan Henning
ROSEMANN & LAURIDSEN GMBH
Am Schlossberg 14, D-82547 Eurasburg, Germany

Phone: +49 700 0200 0700, Fax: +49 81 79 93 07 12
E-Mail: henning -at- r-l -dot- de, Web: www.r-l.de
Handelsregister: München HRB 99345
--------------------------------------------------------------------


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check it out! Get some cool freebies when you buy RoboHelp! You'll receive
SnagIt screen capture software and a 10% discount voucher for RoboHelp
Consulting. This special offers expires March 29, 2002.
www.ehelp.com/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

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