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.
Subject:Re: Technical Writers Needed for API Doc: Really? From:Michael Oboryshko <obie1121 -at- yahoo -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Sat, 12 Jan 2002 12:57:37 -0800 (PST)
> API guides are mostly raw information intended
> for a very limited audience that is looking for specific
> information. API guides don't need to be particularly
> "friendly." Its just a matter of getting all the functions,
> classes, and whatever documented.
True, programmers have become desensitized to bad API docs, but
it doesn't have to be that way.
I make the argument that API docs are critical to sales and
pre-sales of your API. APIs exist so the customer can connect
their product with your product. If your docs convince them it's
easy to use your API, then you are on your way to making a sale.
Better yet, if your API docs enable your prospect's developers
to get a prototype up and running the same day, they are likely
to give your API a positive review.
But that level of results requires more than just a JavaDoc
skeleton with a few comments typed in by the programmer. It
requires on-target code examples, overviews that are helpful but
not bloated, conceptual explanations where required,
task-oriented writing, good indexing, and non-text resources
such as as access to testbed servers. Raw JavaDoc indexes
everything by the object name (or method, property, etc.) -- not
very helpful on Day One.
If you are trying to sell an API, you might not be selling
directly to programmers. The first person to see your API might
be an executive or project manager. Even if their eyes glaze
over with the technical aspects, they will be impressed with a
complete and well-organized API guide. A bad or unfriendly API
doc might end the sale right there.
On one gig I was brought in to document an API. My first job was
to explain the situation to the sales force. They knew how to
sell apps and services, but they weren't really sure what an API
was or how to sell it. I tried, but I don't think my
explanations were really effective until I had a critical mass
of documentation to show them, and I could demo a few function
calls. Then the lights went on. Eventually, the API docs were
prominently featured in their sales pitch, and were directly
credited with winning some new sales. One new, previously
unknown client used the API docs to build a prototype without
our knowledge. One day out of the blue they called to say "We're
ready, where do we send the check?" That made an impression on
the sales guys.
On the other hand, bad API docs can be welfare for Professional
Services staff :)
Regards,
Mike O.
__________________________________________________
Do You Yahoo!?
Send FREE video emails in Yahoo! Mail! http://promo.yahoo.com/videomail/
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr
---
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.
