Re: Technical Writers Needed for API Doc: Really?
Hi all,
I'm looking for resources (an article, a particular messsage in a forum, a page on web site...) that talk about the added-value of technical writers when it comes to documenting an API.
All CTOs and most of the programmers I've met till now keep on saying that only a programmer can produce documentation for programmers. As you can imagine, I've tried convincing them by defining more precisely what a technical writer is and what it can bring to such projects.
...
Cedric,
Like many of your respondents, I don't have the citable sources you seek, only anecdotal evidence. I write API documentation (among other things), and I have seen that having the programmers who developed the API write the doc can be a real problem.
They tend to suffer from a "programmers R us" illusion. Developers skilled enough to build a good API are *not* the programmers for whom that API is developed. APIs provide programming hooks into complex systems that the user of that system is typically either unable (skill or experience-wise) or unwilling (time or budget-wise) to develop for him/herself. Often, users of APIs are less experienced with the particular tools, standards, or programming languages than are those who developed the system and the API.
That said, writing API documentation does not have to be dull. True, if all you develop is reference style material (such as Javadoc, an excellent tool for Java APIs, produces), then it *can* be a little mechanical. But reference is not the end-all of API documentation.
Typically, programmers need task-oriented information just as much as other categories of customers. There *are* those programmers who just use the reference (or who will tell you they do). And you cannot omit the reference. But the less experienced your audience, the more they need the conceptual and procedural information that a task-oriented programming guide can provide. Structuring such a guide, organizing the concepts so they don't drive readers away, and planning and producing examples that illustrate the tasks are anything but boring tasks.
As a skilled technical writer, you can offer a *LOT* to a team that needs API documentation. I hope this helps.
V.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
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.
References:
Technical Writers Needed for API Doc: Really?: From: Cedric Simard
Previous by Author:
RE: Localization Issues
Next by Author:
RE: A cautionary tale
Previous by Thread:
RE: Technical Writers Needed for API Doc: Really?
Next by Thread:
Re: Technical Writers Needed for API Doc: Really?
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads