RE: Creating an FM9 Style to Apply Forced Page Breaks
In class, and in practice, I preach the "Design to 95% Perfect" rule. If I can't handle any of my numbering, referencing, and pagination at arm's length in my template, then I let it go. In my world, a consistent and predictable 95% perfect beats an inconsistent frustrating 100% perfectly formatted document every time. Of course, I also tell my clients that I can help with everything but the politics...including a supervisor who wants to make Frame (and the authors) jump through hoops all day long for trivial formatting issues. I'd suggest you attach a dollar figure to the time associated with the extra formatting, double-checking required by the formatting, and time associated with discussing the formatting. If management feels that sacraficing that money and productivity is worth the nominal improvement in the documentation, there's not much you can do, short of looking for job postings here... -Matt Matt Sullivan GRAFIX Training m...@roundpeg.com www.roundpeg.com Office 714 960-6840 Cell & text 714 585-2335 SMS message 7145852...@vtext.com skype: mattatroundpeg LinkedIn: http://www.linkedin.com/in/grafixtraining facebook| plaxo Click to tell me the social media sites you belong to -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Alison Craig Sent: Thursday, June 25, 2009 5:13 PM To: William Abernathy; framers@lists.frameusers.com Subject: RE: Creating an FM9 Style to Apply Forced Page Breaks I already use this method (for almost any kind of heading) - and I have widow/Orphan control set to a more than just a couple of lines - but it doesn't cover all situations. Thanks, Alison -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of William Abernathy Sent: Thursday, June 25, 2009 2:39 PM To: framers@lists.frameusers.com Subject: Re: Creating an FM9 Style to Apply Forced Page Breaks If you need to insert these breaks in running text for aesthetic reasons (i.e., you don't want to have a heading and three lines of body text, followed by a page break), consider using the "Keep With Next Paragraph" exception in the paragraph definition. This is no more effort than inserting a dummy paragraph to force the page break, and has the benefit of lower maintenance -- If the upstream formatting changes, you stand a much better chance of the break falling in a logical/aesthetic fashion than if you force a break (either with a P-tag exception or by inserting a dummy paragraph). Once either paragraph crosses the page boundary, the break is redrawn in a way that looks good. I believe it is also possible to program this behavior into your body text definition's Widow/Orphan Lines control, but I have not investigated this. --William Alison Craig wrote: > Is there a way to create a style that accepts all existing formatting and > simply applies (i.e., forces) a page break? My attempts to create such a > style have failed so far. > > I really don't want to have to create an Override every time I want a page > break based on layout/esthetic reasons. > > Alison ___ You are currently subscribed to Framers as alison.cr...@ultrasonix.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/alison.craig%40ultrasoni x.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 m...@grafixtraining.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/matt%40grafixtraining.co m 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.
Creating an FM9 Style to Apply Forced Page Breaks
In class, and in practice, I preach the "Design to 95% Perfect" rule. If I can't handle any of my numbering, referencing, and pagination at arm's length in my template, then I let it go. In my world, a consistent and predictable 95% perfect beats an inconsistent frustrating 100% perfectly formatted document every time. Of course, I also tell my clients that I can help with everything but the politics...including a supervisor who wants to make Frame (and the authors) jump through hoops all day long for trivial formatting issues. I'd suggest you attach a dollar figure to the time associated with the extra formatting, double-checking required by the formatting, and time associated with discussing the formatting. If management feels that sacraficing that money and productivity is worth the nominal improvement in the documentation, there's not much you can do, short of looking for job postings here... -Matt Matt Sullivan GRAFIX Training matt at roundpeg.com www.roundpeg.com Office 714 960-6840 Cell & text 714 585-2335 SMS message 7145852335 at vtext.com skype: mattatroundpeg LinkedIn: http://www.linkedin.com/in/grafixtraining facebook| plaxo Click to tell me the social media sites you belong to -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Alison Craig Sent: Thursday, June 25, 2009 5:13 PM To: William Abernathy; framers at lists.frameusers.com Subject: RE: Creating an FM9 Style to Apply Forced Page Breaks I already use this method (for almost any kind of heading) - and I have widow/Orphan control set to a more than just a couple of lines - but it doesn't cover all situations. Thanks, Alison -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of William Abernathy Sent: Thursday, June 25, 2009 2:39 PM To: framers at lists.frameusers.com Subject: Re: Creating an FM9 Style to Apply Forced Page Breaks If you need to insert these breaks in running text for aesthetic reasons (i.e., you don't want to have a heading and three lines of body text, followed by a page break), consider using the "Keep With Next Paragraph" exception in the paragraph definition. This is no more effort than inserting a dummy paragraph to force the page break, and has the benefit of lower maintenance -- If the upstream formatting changes, you stand a much better chance of the break falling in a logical/aesthetic fashion than if you force a break (either with a P-tag exception or by inserting a dummy paragraph). Once either paragraph crosses the page boundary, the break is redrawn in a way that looks good. I believe it is also possible to program this behavior into your body text definition's Widow/Orphan Lines control, but I have not investigated this. --William Alison Craig wrote: > Is there a way to create a style that accepts all existing formatting and > simply applies (i.e., forces) a page break? My attempts to create such a > style have failed so far. > > I really don't want to have to create an Override every time I want a page > break based on layout/esthetic reasons. > > Alison ___ You are currently subscribed to Framers as alison.craig at ultrasonix.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/alison.craig%40ultrasoni x.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as matt at grafixtraining.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/matt%40grafixtraining.co m Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Typing conditional text
FrameMaker 8.0p277, Windows XP SP3. Am I correct that FrameMaker's behavior when you type an Enter in conditionalized text changed before version 8.0? The behavior I'm seeing in FM8.0 seems flat-out wrong to me, and is driving me crazy. I older versions of FrameMaker (at least through 7.0, which is the other version I have on my system), if you type Enter with the insertion point at the very end of a paragraph that is conditionalized, you get a conditionalized pilcrow in the existing paragraph and the new paragraph is unconditional. This was a little annoying if you wanted the next paragraph to also be conditional, but there was an easy workaround, which was to always keep a space between the insertion point and the end of the paragraph. That way, the new paragraph would be non-empty, and FrameMaker would apply the condition to it. Perfectly logical, and everything just worked. But in FrameMaker 8.0, if you type Enter in a paragraph that is entirely conditionalized, the *new* pilcrow (the one that is inserted at the end of the conditional paragraph you've been typing is always *unconditional* and the *following* pilcrow is always *conditional*. This is just plain wrong, because the unconditional pilcrow on the otherwise conditional paragraph will always produce an extra line space when you hide the condition. And if the following paragraph is actually non-conditional, having a conditional pilcrow at its end will make it collapse into the paragraph that follows it when the condition is hidden. I find myself having to spend a lot of time manually conditionalize and unconditionalizing pilcrows throughout the documents I work on. And it's only made worse by the fact that the developers who write the initial drafts of the docs and apply the conditions usually don't even see the pilcrows because the won't follow my advice to always work with View Text Symbols turned on. Am I the only person who has noticed this? I wasted about a half hour trying to find anything about this misbehavior in the Adobe Knowledgebase. Does anyone have a workaround? Does FrameMaker 9 behave the same way (not that I'd be able to recommend having to spend money to upgrade the dozen or so developers to the new version...)? Fred Ridder
RE: Creating an FM9 Style to Apply Forced Page Breaks
I already use this method (for almost any kind of heading) - and I have widow/Orphan control set to a more than just a couple of lines - but it doesn't cover all situations. Thanks, Alison -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of William Abernathy Sent: Thursday, June 25, 2009 2:39 PM To: framers@lists.frameusers.com Subject: Re: Creating an FM9 Style to Apply Forced Page Breaks If you need to insert these breaks in running text for aesthetic reasons (i.e., you don't want to have a heading and three lines of body text, followed by a page break), consider using the "Keep With Next Paragraph" exception in the paragraph definition. This is no more effort than inserting a dummy paragraph to force the page break, and has the benefit of lower maintenance -- If the upstream formatting changes, you stand a much better chance of the break falling in a logical/aesthetic fashion than if you force a break (either with a P-tag exception or by inserting a dummy paragraph). Once either paragraph crosses the page boundary, the break is redrawn in a way that looks good. I believe it is also possible to program this behavior into your body text definition's Widow/Orphan Lines control, but I have not investigated this. --William Alison Craig wrote: > Is there a way to create a style that accepts all existing formatting and > simply applies (i.e., forces) a page break? My attempts to create such a > style have failed so far. > > I really don't want to have to create an Override every time I want a page > break based on layout/esthetic reasons. > > Alison ___ You are currently subscribed to Framers as alison.cr...@ultrasonix.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/alison.craig%40ultrasonix.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.
Creating an FM9 Style to Apply Forced Page Breaks
I already use this method (for almost any kind of heading) - and I have widow/Orphan control set to a more than just a couple of lines - but it doesn't cover all situations. Thanks, Alison -Original Message- From: framers-bounces at lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of William Abernathy Sent: Thursday, June 25, 2009 2:39 PM To: framers at lists.frameusers.com Subject: Re: Creating an FM9 Style to Apply Forced Page Breaks If you need to insert these breaks in running text for aesthetic reasons (i.e., you don't want to have a heading and three lines of body text, followed by a page break), consider using the "Keep With Next Paragraph" exception in the paragraph definition. This is no more effort than inserting a dummy paragraph to force the page break, and has the benefit of lower maintenance -- If the upstream formatting changes, you stand a much better chance of the break falling in a logical/aesthetic fashion than if you force a break (either with a P-tag exception or by inserting a dummy paragraph). Once either paragraph crosses the page boundary, the break is redrawn in a way that looks good. I believe it is also possible to program this behavior into your body text definition's Widow/Orphan Lines control, but I have not investigated this. --William Alison Craig wrote: > Is there a way to create a style that accepts all existing formatting and > simply applies (i.e., forces) a page break? My attempts to create such a > style have failed so far. > > I really don't want to have to create an Override every time I want a page > break based on layout/esthetic reasons. > > Alison ___ You are currently subscribed to Framers as alison.craig at ultrasonix.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/alison.craig%40ultrasonix.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Creating an FM9 Style to Apply Forced Page Breaks
If you need to insert these breaks in running text for aesthetic reasons (i.e., you don't want to have a heading and three lines of body text, followed by a page break), consider using the "Keep With Next Paragraph" exception in the paragraph definition. This is no more effort than inserting a dummy paragraph to force the page break, and has the benefit of lower maintenance -- If the upstream formatting changes, you stand a much better chance of the break falling in a logical/aesthetic fashion than if you force a break (either with a P-tag exception or by inserting a dummy paragraph). Once either paragraph crosses the page boundary, the break is redrawn in a way that looks good. I believe it is also possible to program this behavior into your body text definition's Widow/Orphan Lines control, but I have not investigated this. --William Alison Craig wrote: > Is there a way to create a style that accepts all existing formatting and > simply applies (i.e., forces) a page break? My attempts to create such a > style have failed so far. > > I really don't want to have to create an Override every time I want a page > break based on layout/esthetic reasons. > > Alison ___ 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.
Creating an FM9 Style to Apply Forced Page Breaks
If you need to insert these breaks in running text for aesthetic reasons (i.e., you don't want to have a heading and three lines of body text, followed by a page break), consider using the "Keep With Next Paragraph" exception in the paragraph definition. This is no more effort than inserting a dummy paragraph to force the page break, and has the benefit of lower maintenance -- If the upstream formatting changes, you stand a much better chance of the break falling in a logical/aesthetic fashion than if you force a break (either with a P-tag exception or by inserting a dummy paragraph). Once either paragraph crosses the page boundary, the break is redrawn in a way that looks good. I believe it is also possible to program this behavior into your body text definition's Widow/Orphan Lines control, but I have not investigated this. --William Alison Craig wrote: > Is there a way to create a style that accepts all existing formatting and > simply applies (i.e., forces) a page break? My attempts to create such a > style have failed so far. > > I really don't want to have to create an Override every time I want a page > break based on layout/esthetic reasons. > > Alison
Typing conditional text
FrameMaker 8.0p277, Windows XP SP3. Am I correct that FrameMaker's behavior when you type an Enter in conditionalized text changed before version 8.0? The behavior I'm seeing in FM8.0 seems flat-out wrong to me, and is driving me crazy. I older versions of FrameMaker (at least through 7.0, which is the other version I have on my system), if you type Enter with the insertion point at the very end of a paragraph that is conditionalized, you get a conditionalized pilcrow in the existing paragraph and the new paragraph is unconditional. This was a little annoying if you wanted the next paragraph to also be conditional, but there was an easy workaround, which was to always keep a space between the insertion point and the end of the paragraph. That way, the new paragraph would be non-empty, and FrameMaker would apply the condition to it. Perfectly logical, and everything just worked. But in FrameMaker 8.0, if you type Enter in a paragraph that is entirely conditionalized, the *new* pilcrow (the one that is inserted at the end of the conditional paragraph you've been typing is always *unconditional* and the *following* pilcrow is always *conditional*. This is just plain wrong, because the unconditional pilcrow on the otherwise conditional paragraph will always produce an extra line space when you hide the condition. And if the following paragraph is actually non-conditional, having a conditional pilcrow at its end will make it collapse into the paragraph that follows it when the condition is hidden. I find myself having to spend a lot of time manually conditionalize and unconditionalizing pilcrows throughout the documents I work on. And it's only made worse by the fact that the developers who write the initial drafts of the docs and apply the conditions usually don't even see the pilcrows because the won't follow my advice to always work with View Text Symbols turned on. Am I the only person who has noticed this? I wasted about a half hour trying to find anything about this misbehavior in the Adobe Knowledgebase. Does anyone have a workaround? Does FrameMaker 9 behave the same way (not that I'd be able to recommend having to spend money to upgrade the dozen or so developers to the new version...)? Fred Ridder ___ 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.
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-request at lists.frameusers.com wrote: Message: 1 Date: Wed, 24 Jun 2009 16:50:21 -0700 From: "Carl Yorke" Subject: Developer documentation To: Message-ID: 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
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 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.
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" Subject: Developer documentation To: Message-ID: 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.
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.
Developer documentation
On Wed, Jun 24, 2009 at 7:50 PM, Carl Yorke wrote: > Now I need to write developer documentation, which doesn't make sense to > me. Is that *all* they told you? -- Milan Davidovic http://altmilan.blogspot.com
Developer documentation
Re: Developer documentation
___ 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
On Wed, Jun 24, 2009 at 7:50 PM, Carl Yorke wrote: > Now I need to write developer documentation, which doesn't make sense to > me. Is that *all* they told you? -- Milan Davidovic http://altmilan.blogspot.com ___ 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.
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