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