Developer documentation

[Reid Gray]

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 developers.
 
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" example. 
 
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 code.
 
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!
 
Reid

________________________________

From: framers-bounces at lists.frameusers.com on behalf of Chris Despopoulos
Sent: Thu 6/25/2009 8:16 AM
To: framers at lists.frameusers.com
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 tasks
* 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 useful...

cud



     
_______________________________________________


You are currently subscribed to Framers as rgray at interactivesupercomputing.com.

Send list messages to framers at lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscribe at lists.frameusers.com
or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com

Send administrative questions to listadmin at frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.