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.
Re: Difference between developer guide content and reference information
Subject:Re: Difference between developer guide content and reference information From:Bill Swallow <techcommdood -at- gmail -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Sun, 24 Apr 2005 23:55:23 -0400
Many 3rd party "reference" books are actually dev guides. If you want
a good contrast of a dev guide and a tech reference, install and read
any SDK/API reference, and then take a look at supporting
documentation for the same SDK/API. The reference should follow the
object model and provide discreet info about each property, method,
constructor, etc. Sure, these topics can (and should) contain sample
code to illustrate use and overview info where appropriate as to what
the thing is and how it's intended to be used. But, dev guides should
literally guide developers through the object model at a higher
altitude and explain the SDK/API in a more purposeful way. The
developers not only need to get exact info about members of the object
model they're working with, but they need to "get" the object model as
well. I think you're on target with your thoughts on what a dev guide
should look like. The reference should be much drier. ;-)
On 4/24/05, rachna_bhutani -at- yahoo -dot- com <rachna_bhutani -at- yahoo -dot- com> wrote:
>
> I have to create a developer guide and a product reference (guide?) for
> the same product. These documents will enable developers to create
> applications based on the product. However, I am unclear about the type of
> content that should be included in each guide. I would appreciate inputs
> on how to decide what should go into a developer guide, and what should go
> into a product reference document.
>
> According to me, a developer guide should have an architectural overview,
> information about key system components, steps in developing an
> application, configuration and security information. However, I have
> looked at various books, and the reference books also seem to have the
> same topics. Both also have code examples. The only difference I noticed
> was that the reference books contained a great deal of code examples to
> explain the usage and functionality of the functions/methods, classes,
> fields etc, whereas the developer guides didn't have as many code
> examples.
>
> Suggestions on what kind of information to include in each document would
> be most helpful.
WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo: http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
