RE: Developer documentation
Combining advice, experience, sympathy, and grins: http://geekandpoke.typepad.com/geekandpoke/ http://geekandpoke.typepad.com/geekandpoke/2009/06/what-geeks-love-part-2.html ___ Sheila Carlisle V: 425/ 486-2988 F: 425/ 483-3836 Axial InfoSolutions Inc. (Bothell, Washington) Automated Publishing Solutions / XML Publishing Solutions http://www.axialinfo.com http://www.miramo.com -Original Message- Now I need to write developer documentation 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.
Re: Developer documentation
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. Have you consulted with your developer management to define what they think should be in the documentation? -- John Posada Senior Technical Writer NYMetro STC President Looking for the next gig. ___ 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.
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 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.
RE: Developer documentation
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.
Re: Developer documentation
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.
