Re: Recommendations for programmer's guides

Subject: Re: Recommendations for programmer's guides
From: "Peter Neilson" <neilson -at- windstream -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Tue, 25 Aug 2015 06:30:48 -0400

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:

Hi all,

Either writing programmer's guides is as much a dying art as tech authoring is rumoured to be, or my query is too daft to answer - but I got no responses to my original plea for help, so I'm displaying my capacity for audacity by reposting.


----------------------------------------------------------------------


I have not worked on programmer's guides but now have the opportunity to do so. The initial draft I have seen looks rather sparse and not the best structure. Please can anyone recommend a decent example of a programmer's guide that I can look at for comparison?

I particularly need to know what the range of contents might need to be, as well as structure. We have format templates to use/adapt.

If the example contains or is accompanied by a Reference Design, that would be even better.

Many thanks for your help (pretty please?),

Heidi
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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


Follow-Ups:

References:
Recommendations for programmer's guides: From: Teddie H

Previous by Author: Re: Business Glossary
Next by Author: Re: Phrasing question in documentation
Previous by Thread: 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


Sponsored Ads