Re: Contents, Focus of Developer's Guide

Subject: Re: Contents, Focus of Developer's Guide
From: "Mike O." <obie1121 -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 4 Nov 2003 11:10:44 -0500

Vlad Dracul wrote:
> I would like to know your opinions on the following:
> * If a user guide for developers should be called a developer's guide,
> in what way would the developer's guide differ from other user guides?
> * What is the focus of a developer's guide?
> * What does a developer's guide typically contain?

Hi Vlad, did you have a nice Halloween? :-)

It doesn't matter what you call it - that's a business decision, you can
work it out with your team.

But I agree with you that a developers guide is just a user guide for a
different audience; in fact I think I have posted on this topic before in
more detail. Your approach should be the same: find out what your users
want/need/expect, and then give it to them.

Some practical tips:
- Use the form your developers expect. If it's java, use javadoc. If it's
perl, use pod, etc.
- Give plenty of examples, with code that can be cut and pasted and actually
works. Test it yourself.
- Try to get your team to establish a public or semi-public test server
where developers can test sample code from the manual.

Don't underestimate the power of a test server. If developers had to choose
between "a great manual" and "a live test server" they would choose the
server every time.

- A developers guide would minimally contain a reference section that
describes the API or function calls the developers would use.

Ask your developers to provide a list of the Top Ten most common scenarios a
developer would need to do with your middleware. Then create a topic for
each, and fully walk the reader through it in detail, with code examples.
That's not a bad start for a How To section.

Mike O.



RoboHelp for FrameMaker is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to online Help, intranet, and Web.
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! Call 800-718-4407 for
competitive pricing or download a trial at:

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: Re: Offshore writers and editors
Next by Author: Re: English major?
Previous by Thread: RE: Contents, Focus of Developer's Guide
Next by Thread: Re: Contents, Focus of Developer's Guide

What this post helpful? Share it with friends and colleagues:

Sponsored Ads