Developer documentation

[dwyercl2 at verizon.net]

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