[Author Prev][Author Next][Thread Prev][Thread Next]
[Author Index (this month)][Thread Index (this month)][Top of Archive]

Re: Writing APIs, was "About The Cloud: Quick-Read Suggestions"

Subject: Re: Writing APIs, was "About The Cloud: Quick-Read Suggestions"
From: "Peter Neilson" <neilson -at- windstream -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Fri, 05 Apr 2013 13:06:38 -0400

On Fri, 05 Apr 2013 12:02:30 -0400, Robert Lauriston <robert -at- lauriston -dot- com> wrote:

The most common flaw I've encountered in API documentation was missing
or inadequate sample code.

Though if the API exists only to please bean counters, that may be intentional.

I've had the argument about sample code with developers over the years, from time to time. Here are some the flavors of possible reasons for omitting it:

"Any good coder can write code from the specs. Anyone who needs an example shouldn't be coding."

"The toy example you see there isn't using the real API. We'll give you a real example after the API design is finished."

"If we put in an example and the API changes, we'd have to provide a new example."

From the documentation side I have provided a somewhat different opinion: "Did you test that example code? I just did, and it doesn't work. What should we do?"

Perhaps the tech writer's job is to make sure that the hubris hits the rotating blades early and gently, when there is less possibility of damage.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
From our sponsor Doc-to-Help: Want to see a Doc-To-Help web-based Help sample with DISQUS for user commenting?

Learn more: http://bit.ly/13xpg5n

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives

Follow-Ups:

References:
re: Writing APIs, was "About The Cloud: Quick-Read Suggestions": From: Bowes, Rebecca
RE: Writing APIs, was "About The Cloud: Quick-Read Suggestions": From: Combs, Richard
Re: Writing APIs, was "About The Cloud: Quick-Read Suggestions": From: sphilip

Previous by Author: Re: Wikipedia question
Next by Author: Re: a question about outcomes in a syllabus
Previous by Thread: Re: Writing APIs, was "About The Cloud: Quick-Read Suggestions"
Next by Thread: Re: Writing APIs, was "About The Cloud: Quick-Read Suggestions"

[Top of Archive] | [Author Index (this month)] | [Thread Index (this month)]

What this post helpful? Share it with friends and colleagues:

Sponsored Ads