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-boun...@lists.frameusers.com on behalf of Chris Despopoulos
Sent: Thu 6/25/2009 8:16 AM
To: framers@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 rg...@interactivesupercomputing.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/rgray%40interactivesupercomputing.com
Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.
_______________________________________________
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.
