This builds on the comments by Chris.

You definitely need:

- Pre-requisites for the software

- Unpacking the software

- Architecture diagram.  (Typically in an overview section)
The architecture diagram identifies where the custom application these 
developers will code fits in the scheme of the application framework, the 
platform, and the network.  What libraries must it include?  What platforms are 
these libraries available on?  What methods or protocols are used to pass data?

- Working examples.
Programming or developer documentation is best when it contains working 
examples.  You can can these from systems engineers, sales engineers, or 

Most examples have a step where you create or construct an object and use its 
methods or add or get data from that object.  This would be your "hello world" 

Nice to have:

- Class diagrams.
If your stuff inherits methods from base classes, it is nice to show this.  
There are also 3rd party tools that can generate these diagrams right from the 

Examples of complete custom apps (in an appendix for instance).

Things to be aware of:

Chances are that your programming interfaces follow or demonstrate qualities of 
a particular design pattern.  Find out what design pattern the interfaces 
follow before you begin to write. You can familiarize yourself with the design 
pattern's basic concepts and philosophy very quickly by looking it up on 
Wikipedia and discussing with your favorite developer. This information 
provides your frame of reference as you write.

Find out and establish early on what should be visible to the end-user or 
developer and what is opaque.  Otherwise, you could spend a lot of time writing 
about interfaces used in house but not for customers except maybe where the 
customer is a partner.

All in all your project sounds cool.

Have fun!



From: on behalf of Chris Despopoulos
Sent: Thu 6/25/2009 8:16 AM
To: framers at
Subject: Re: Developer documentation

I'll take a crack at this...

You should try to find developer docs that you can emulate. To start, you need 
to figure out some particulars of the dev platform -- what language (C/C++, 
Java, Flash, etc.), what is the dev environment (is there a specific IDE 
(integrated development environment) you support?), is this an API into a 
proprietary game engine, or a framework for integrating external technologies 
like Flash into a TV platform?  Understanding and being able to articulate 
these issues will help you find examples of docs that approximate your goal.  
Don't stick to "Dev docs for TV Games" -- cast a wider net.

You can look at any dev good docs and hope to see the following:
* Overview/description/use cases --  Why even bother with this dev environment
* Architecture -- How is the platform organized, what talks to what, and what 
components do you program
* Dev tools -- Languages and IDEs supported
* Installation and use -- How to link your technology into a program
* Hello World -- The smallest possible program. This is important because the 
customer can use it to prove the installation is good
* Sample "recipes" -- Nice to have...  listings of code that performs specific 
* Reference -- Each method, function, or whatever types of calls you expose 
with the signature (what you pass in and what it returns), synopsis, required 
libs or packages, discussion (only use this method if the moon is full), and 
maybe sample code

There's stuff to look at.  Look at the MSDN - Microsoft Developer's Network.

So... is this advice, experience, or sympathy?  Whatever it is, I hope it's 



You are currently subscribed to Framers as rgray at

Send list messages to framers at

To unsubscribe send a blank email to
framers-unsubscribe at
or visit

Send administrative questions to listadmin at Visit for more resources and info.

Reply via email to