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 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?
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?
