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.
Matthew Horn wrote:
> I don't think I know anyone who documents web
> services. And the ones that i have used don't
> really require much more doc than telling me what
> the return values are. Maybe there is more
> to it than I think....
You're absolutely right; docs for web service APIs
usually don't do much more than tell you what the
return values are.
But once web services actually get some paying
customers, I expect the customers will demand (or at
least appreciate) some more fleshed-out doc that
includes examples and conceptual information.
API developers tend to script out a skeleton HTML
framework, maybe fill in a few sentences, and call it
"API documentation." Well, that's better than nothing
and it might be good enough, but if you want to offer
your API in a competitive commercial situation you
should get an actual writer to finish the job.
Programmers have learned to tolerate skimpy API docs,
but they are amazed and gratified when they find
something better.
I documented an XML-based API for a dot-com. and the
examples and background info in the docs were credited
with some sales of web services, because the client
developers assigned to evaluate the API were able to
get up and running quickly, and were able to give a
glowing report to their boss. Didn't save the
dot-com, though :-(
Mike O.
__________________________________
Do you Yahoo!?
Yahoo! SiteBuilder - Free, easy-to-use web site design software http://sitebuilder.yahoo.com
NEED TO PUBLISH FRAMEMAKER CONTENT ONLINE? "Mustang" is a NEW single
sourcing tool for FrameMaker that lets you easily publish your content
online. No macro language required! http://www.ehelp.com/techwr-l3
Mercer University's online MS Program in Technical Communication Management:
Preparing leaders of tomorrow's technical communication organizations today.
See www.mercer.edu/mstco or write George Hayhoe at hayhoe_g -at- mercer -dot- edu -dot-
---
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.
