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

Subject: Re: Writing APIs, was "About The Cloud: Quick-Read Suggestions"
From: Keith Hood <klhra -at- yahoo -dot- com>
To: Peter Neilson <neilson -at- windstream -dot- net>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 5 Apr 2013 15:17:02 -0700 (PDT)

I think the argument about having to change the sample is the only one that is really sensible, but even that is not conclusive.  If they change anything, the ANY documentation referring to that code has to be changed.  Ask the developers if they are are as good as they want to think they are, why is changing the example so terribly difficult that they don't want to do it?


In an honest to the gods case of hubris, there is no way to gentleize* the fan blade impact.  Wear your smock and face shield in all such cases.

* Archaic usage; deprecated



________________________________
From: Peter Neilson <neilson -at- windstream -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Sent: Friday, April 5, 2013 12:06 PM
Subject: Re: Writing APIs, was "About The Cloud: Quick-Read Suggestions"

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 klhra -at- yahoo -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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>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


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
Re: Writing APIs, was "About The Cloud: Quick-Read Suggestions": From: Peter Neilson

Previous by Author: Re: Justifying FM
Next by Author: Re: another question about designing an instructor-led course
Previous by Thread: Re: Writing APIs, was "About The Cloud: Quick-Read Suggestions"
Next by Thread: TechWhirl: Technical Communication Recap for April 5, 2013


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


Sponsored Ads