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.
> I'd appreciate any pointers you have to "best of
> breed" developer or API documentation.
I was hired as a consultant in March 2000 to develop
API documentation for eCal's XML-based API (eCAPI).
The result is available at http://developer.ecal.com.
This API provides an interface for customers to build
scheduling and notification applications using eCal's
hosted database.
I developed most of the doc content and passed HTML
files to their webmaster, so I can't claim credit for
the website design. Their webmaster maintains the
website using PHP and MySQL.
I didn't know XML when I took the job; in fact on the
way home from the interview I stopped at Borders and
bought an XML book.
I modeled the info after the successful WinHelp system
for Visual Basic, in that I knew it needed lots of
working sample code that developers could cut and
paste into their code. Fortunately, eCal had the
foresight to provide a public test server where
developers can post their sample code and get
immediate gratification (in the form of returned
data). So it was very important that all the sample
code work flawlessly; if it was buggy the
documentation would lose credibility. So most of my
work effort on this project was spent developing and
validating sample XML.
The main components of this API guide are:
- Conceptual overviews, miscellanous info (general
info)
- Task oriented procedures (how to)
- Reference documentation (annotated DTD)
- Sample XML (cut and paste; use immediately)
This API is intended primarily for external customers,
and it seemed to be well received...and since the API
is its own profit center, this documentation became
highly visible. The sales team appreciated it because
it answers a lot of customers' technical questions up
front. One of the execs at the time attributed a good
amount of new business to this website. It's not often
that tech writers get to be counted toward revenue
rather than overhead!
Many shops now are seeking to expose their APIs to
their customers, and all those APIs are going to need
documentation...
Regards,
Mike O.
obie1121 -at- yahoo -dot- com
__________________________________________________
Do You Yahoo!?
Get email at your own domain with Yahoo! Mail. http://personal.mail.yahoo.com/
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com
Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East,
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline
April 27. http://www.pdfconference.com.
---
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.
