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-requ...@lists.frameusers.com wrote:
Message: 1
Date: Wed, 24 Jun 2009 16:50:21 -0700
From: "Carl Yorke" <carl.yo...@playtag.com>
Subject: Developer documentation
To: <framers@lists.frameusers.com>
Message-ID: <e2c8ca279008ce48a1b777434172fb73a31...@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
_______________________________________________
You are currently subscribed to Framers as arch...@mail-archive.com.
Send list messages to fram...@lists.frameusers.com.
To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com
Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.
