Re: Recommendations for programmer's guides

["Peter Neilson" <neilson -at- windstream -dot- net>]

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?

On Tue, 25 Aug 2015 05:42:56 -0400, Teddie H <teddiehmb -at- hotmail -dot- com> wrote: