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

Subject: Re: Writing APIs, was "About The Cloud: Quick-Read Suggestions"
From: Richard Hamilton <dick -at- rlhamilton -dot- net>
To: TECHWR-L Writers <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 5 Apr 2013 11:36:31 -0700

Good points.

I've never heard a reader complain about too many examples.

They are a pain to write and to keep accurate and up-to-date, but they are valuable to readers, and that's who we are writing for.

Also, I would argue that they are good for the writer. If you have to include (and test) an example, you will understand the interface better and be able to write about it better.

Best Regards,
Richard
-------
XML Press
XML for Technical Communicators
http://xmlpress.net
hamilton -at- xmlpress -dot- net



On Apr 5, 2013, at 10:06 AM, Peter Neilson wrote:

> 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 dick -at- rlhamilton -dot- net -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: About The Cloud: Quick-Read Suggestions
Next by Author: RE: New TechWhirl Poll: Wearable Computers Changing Tech Comm? Vote and Comment
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"


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


Sponsored Ads