Carl,

The programmer's guide I helped to write several years ago was done with 
complete collaboration with the developers -- they were great! The project we 
were working on had an API (application programmer's interface) that we fully 
documented, along with definitions of acronyms and terms that were particular 
to our product. It is still in use today and is being updated as new features 
are added to the product.

We started with a basic introduction to the "underbelly" of the product, its 
servers, its clients, and its API. We then divided the rest of the document 
into defining, describing, and giving examples of code (lots!) for each 
specific aspect of the product that the developers had already created, were 
creating, or would have to create. This also included defining notifiers, 
listeners, triggers, and any such related events as well as our data model and 
workflow. As our product was Java-based, the APIs were derived from JavaDocs 
and were available to programmers as part of the product installation; we 
provided a pathname to each API for each of area we described.

[Note:  In the first iteration of the doc, we actually downloaded the API and 
published it, links and all. We soon discovered this wasn't used as much as we 
thought it would be (and it was a lot of work!), so we decided to save the 
trees and not include the published version, as the online version was 
available to the developers, which most seemed to prefer anyway...]

The developers I worked with were very busy but realized it was to their 
advantage to have this info documented. I tried to be as non-intrusive in their 
schedules as I could and found that recording my interviews with them helped 
enormously, both with their limited time and my cryptic notes as I sometimes 
wondered what I meant by what I'd written... [I now have a LiveScribe pen 
(www.livescribe.com) that I'd have given my eye teeth for then as it not only 
records what is being said, but it captures your notes to upload as PDF to 
share, if needed, or to "tap on some text" and hear played back what was said 
when you were writing that text. Now it even has a third-party application that 
translates your scripted notes into editable text... love it!]

That said, I could never have tackled this alone; it's the developers who must 
give you the information. Even if you're familiar with programming, there are 
too many areas that must be documented with expert information... so get it 
from the experts themselves.

Good luck!
Cheryl Dwyer
Industrial Medium Software, Inc.
McLean, VA  22102

On Jun 25, 2009, framers-request at lists.frameusers.com wrote:


    Message: 1
    Date: Wed, 24 Jun 2009 16:50:21 -0700
    From: "Carl Yorke" <Carl.Yorke at playtag.com>
    Subject: Developer documentation
    To: <framers at lists.frameusers.com>
    Message-ID: <E2C8CA279008CE48A1B777434172FB73A31625 at mail.tvhead.local>
    Content-Type: text/plain; charset="us-ascii"

    Hi All,

    I am the lone writer in a casual-games-on-television company. I was
    hired to document the platform side with Install Guides and Sys Admin
    Guides which make sense to me.

    Now I need to write developer documentation, which doesn't make sense to
    me. I just can't seem to get an handle on what these books should look
    like.

    I've looked at books about how to build games, but they all seem to be
    selling a particular program or technology. I haven't found any that are
    decently organized or written.

    If anyone has any advice, experience or sympathy, I'm open to all.

    Thanks,
    Carl Yorke

    TAG Networks

Reply via email to