RE: TECHWR-L Digest, Vol 118, Issue 19

Subject: RE: TECHWR-L Digest, Vol 118, Issue 19
From: Teddie H <teddiehmb -at- hotmail -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>, "neilson -at- windstream -dot- net" <neilson -at- windstream -dot- net>, "loisrpatterson -at- gmail -dot- com" <loisrpatterson -at- gmail -dot- com>
Date: Wed, 26 Aug 2015 07:51:28 +0000

Many thanks to Peter and Lois - and those who replied privately.

It is indeed a vague question, and your answers all help me to work out how to make it less vague, maybe.

Looking at the draft I have, it looks like the information provider isn't exactly an expert in this kind of info either. As research/learning budgets are nil, there is a limit to what I can spend time or money on to get up to speed.

Maybe we'll get some good customer feedback to help improve it...

Well, I can dream :-)

Thanks all,

Heidi


> ----------------------------------------------------------------------
>
> Message: 2
> Date: Tue, 25 Aug 2015 06:30:48 -0400
> From: "Peter Neilson" <neilson -at- windstream -dot- net>
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Re: Recommendations for programmer's guides
> Message-ID: <op -dot- x3w55mpcrns8nc -at- odin>
> Content-Type: text/plain; charset=utf-8; format=flowed; delsp=yes
>
> Perhaps your question is too vague. Is the guide for people beginning a
> particular programming language, or is it for advanced programmers who
> will be using a particular API from some particular language, such as
> python use of an API for making phone calls?
>
> The former is rather well covered by existing books about everything from
> JCL to Haskell, in an astounding spread of quality. (The O'Reilly books
> are often regarded as a good standard.)
>
> The latter usually requires examples, which means you'll need to display
> detailed knowledge of both the computer language and the platform to which
> the API connects. You will need to cover the difficulties the programmer
> will encounter, not just the obvious material. In particular it can be
> very hard for a programmer to understand which of six dozen possible
> interface calls is appropriate for a given situation. If you press for
> information, your SME might caution, "Don't use open() but use w_open()
> instead, because open() is mostly obsolete, except in the obvious case
> where w has already been established." (Huh?? "Obvious"???).
>
> 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.)
>
> Does that help at all? Or do your guides go off in some other direction?
>

> ------------------------------
>
> Message: 6
> Date: Tue, 25 Aug 2015 10:59:53 -0700
> From: Lois Patterson <loisrpatterson -at- gmail -dot- com>
> To: Peter Neilson <neilson -at- windstream -dot- net>
> Cc: techwr-l <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: Re: Recommendations for programmer's guides
> Message-ID:
> <CADQ+ZGfm1dPsAMRbTtcGZrMbNZ49hT4KL4eMrz=PH9BJRe0NTg -at- mail -dot- gmail -dot- com>
> Content-Type: text/plain; charset=UTF-8
>
> 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


Previous by Author: Recommendations for programmer's guides
Next by Author: Backup services
Previous by Thread: Re: manual vs white paper
Next by Thread: TechWhirl Fast 5 with Jack Molisani of LavaCon next Wed, Sept 2


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

Sponsored Ads


Sponsored Ads