Re: Recommendations for programmer's guides

Subject: Re: Recommendations for programmer's guides
From: Lois Patterson <loisrpatterson -at- gmail -dot- com>
To: Peter Neilson <neilson -at- windstream -dot- net>
Date: Tue, 25 Aug 2015 10:59:53 -0700

If it helps, suggest to the SME that the guide you are creating should be
targeted at poor-quality programmers, not for the SME himself/herself. With
good enough API documentation, people who know just some coding can create
good-enough applications too. (For example, if you are creating an API and
API docs that physicists will use, the physicist user may know programming,
but not be primarily a developer.)

Lois


On Tue, Aug 25, 2015 at 3:30 AM, Peter Neilson <neilson -at- windstream -dot- net>
wrote:

> [snip]
>
> There is a dilemma in writing API guides, because (1) the tech writer
> will--naturally--not be an expert programmer, and (2) the SME, an expert
> programmer, will deem the task of writing use cases for the API to be
> trivial, and will often produce hand-wavy and untested code. If you simply
> test the SME's example code, find it unusable, and ask the SME, "I don't
> see how this is supposed to work. Is it broken?" you may receive hostile
> insults to your competence. (Been there. Done that.)
>
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Learn more about Adobe Technical Communication Suite (2015 Release) | http://bit.ly/1FR7zNW

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

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:
Recommendations for programmer's guides: From: Teddie H
Re: Recommendations for programmer's guides: From: Peter Neilson

Previous by Author: Does going through a recruiter hurt your chances?
Next by Author: Re: manual vs white paper
Previous by Thread: Re: Recommendations for programmer's guides
Next by Thread: Re: Recommendations for programmer's guides


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


Sponsored Ads