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