Re: Recommendations for programmer's guides

Subject: Re: Recommendations for programmer's guides
From: Lauren <lauren -at- writeco -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Mon, 31 Aug 2015 19:31:03 -0700

Sometimes you need to be persistent to get a response.

All guides, like all technical documents, are written for the audience of the document. API's are written for programmers to know how to use a program or system, usually within or by another program or system, it usually describes various hooks for the program or system. A programmer's guide is written for a programmer to know how a system works and for future building on and within that system. Both types of documents are organized by function, so there is no concise and consistent outline to follow as in user documentation. User documentation usually includes administrative functions to access the system and an organization of steps and operations within the system that are often discussed in order from rudimentary to complex.

A programmer's guide need to have information grouped by function and in order of how programmers will access the various functions with the more common functions described first.

A quick Google, if your Google is trained for finding code, will show several programmer's guides. If your Google is not properly trained, then add keywords to get a list of guides. The search that follows is followed by a selection of documents from my search that are programmer's guides.

https://www.google.com/search?q=programmers+guide

The MSDN Programmer's Guide for Visual Basic is organized in a modified 5 w's format. The sections cover in a programming sort of way Who/What, When, Why/Where, How, Shortcuts/Tools, and Help. Each section spins off to more sections.
https://msdn.microsoft.com/en-us/library/Aa716285(v=VS.60).aspx

Ruby ain't got no pretty guide... It uses the 5 w's in the preface. The Roadmap section describes each section and shows that each section is stepped from simple to advanced.
http://ruby-doc.com/docs/ProgrammingRuby/

There is an assortment of program guides at FTDI Chip. These guides are centered on the commands within the program and group by logical area of the program.
http://www.ftdichip.com/Support/Documents/ProgramGuides.htm

Enjoy,
Lauren


On 8/25/2015 2:42 AM, Teddie H 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? ...

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

Previous by Author: Re: Phrasing question in documentation
Next by Author: Re: FrameUsers update
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


Sponsored Ads