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