Official TGEA Documentation Feedback
by Michael Perry · in Torque Game Engine Advanced · 03/19/2008 (7:21 am) · 102 replies
=========================================================================
This Thread Is The Official Documentation Feedback Area For ALL Versions of TGEA
If you want to quick search for all TGEA Doc Updates, perform a keyword search in your browser for "Documentation Update:"
=========================================================================
Hey Everyone. I've got my nose to the grindstone working on the documentation and tutorials for TGEA, which was provided in the TGEA 1.7.0 Beta.
By using this thread as a central source to leave documentation feedback, we can keep the other forums clean.
Feel free to post any criticism, suggestions, bugs (missing images or dead hyperlinks), outdated information, etc.
Outside of messing up an object or class name, don't worry about correcting grammar or spelling. Believe me, I'll find those eventually =)
Known Issues:
- Missing images in Mission Editor section (Found the reason and will correct it soon)
- Formatting inconsistent (Created a new template and porting finished sections over)
- Missing or Out of Order Table of Contents for quite a few sections. Let me know what you find
- Reference to a Tutorials Section that does not exist.
I want to elaborate on this last part. I really like how the TGB documentation separates its reference and overview sections from its tutorials. If you read through the GUI Editor section, you'll see there is a mini-tutorial. This is used solely for giving an overview of the Editor and its layout. I'm going to create a Tutorial section, and one example for an extended GUI tut would be "Creating An In Game Inventory GUI."
Look forward to the feedback ladies and gents =)
This Thread Is The Official Documentation Feedback Area For ALL Versions of TGEA
If you want to quick search for all TGEA Doc Updates, perform a keyword search in your browser for "Documentation Update:"
=========================================================================
Hey Everyone. I've got my nose to the grindstone working on the documentation and tutorials for TGEA, which was provided in the TGEA 1.7.0 Beta.
By using this thread as a central source to leave documentation feedback, we can keep the other forums clean.
Feel free to post any criticism, suggestions, bugs (missing images or dead hyperlinks), outdated information, etc.
Outside of messing up an object or class name, don't worry about correcting grammar or spelling. Believe me, I'll find those eventually =)
Known Issues:
- Missing images in Mission Editor section (Found the reason and will correct it soon)
- Formatting inconsistent (Created a new template and porting finished sections over)
- Missing or Out of Order Table of Contents for quite a few sections. Let me know what you find
- Reference to a Tutorials Section that does not exist.
I want to elaborate on this last part. I really like how the TGB documentation separates its reference and overview sections from its tutorials. If you read through the GUI Editor section, you'll see there is a mini-tutorial. This is used solely for giving an overview of the Editor and its layout. I'm going to create a Tutorial section, and one example for an extended GUI tut would be "Creating An In Game Inventory GUI."
Look forward to the feedback ladies and gents =)
About the author
Programmer.
#83
My writing process may not be optimized, but it works for me and keeps me running at a good pace. What I usually do is write my docs in Notepad or MS Word. Once I'm satisfied, I'll perform an editing pass checking for grammar and spelling.
From there, I port the docs over to TDN articles. I like TDN for its clean format, and this is where I usually add pictures, code sections, formatting, etc. Once I've ported all the work, I perform another edit pass as well as an accuracy pass on the content.
When I'm completely happy with the doc, I use our in-house converter to port the TDN article to our final .html format. The last thing I have to do is fix any broken links, and integrate into our Doc System.
Why am I telling you all of this? Well, I'm going to try something here. The TGEA 1.7 Beta showed me how capable and helpful our community can be. So, I'm going to release the docs I'm writing in "beta format". You can preview the new docs as I port them to TDN.
I'll be making several edit and preview passes, so you might see entire sections appear or disappear. The docs are all written, but as I stated earlier I'm porting the docs for formatting and content accuracy. When 1.8 reaches full release, I'll push the docs online and into the SDK build.
How does that sound?
TGEA 1.8 Beta Docs
10/28/2008 (10:26 am)
Documentation UpdateMy writing process may not be optimized, but it works for me and keeps me running at a good pace. What I usually do is write my docs in Notepad or MS Word. Once I'm satisfied, I'll perform an editing pass checking for grammar and spelling.
From there, I port the docs over to TDN articles. I like TDN for its clean format, and this is where I usually add pictures, code sections, formatting, etc. Once I've ported all the work, I perform another edit pass as well as an accuracy pass on the content.
When I'm completely happy with the doc, I use our in-house converter to port the TDN article to our final .html format. The last thing I have to do is fix any broken links, and integrate into our Doc System.
Why am I telling you all of this? Well, I'm going to try something here. The TGEA 1.7 Beta showed me how capable and helpful our community can be. So, I'm going to release the docs I'm writing in "beta format". You can preview the new docs as I port them to TDN.
I'll be making several edit and preview passes, so you might see entire sections appear or disappear. The docs are all written, but as I stated earlier I'm porting the docs for formatting and content accuracy. When 1.8 reaches full release, I'll push the docs online and into the SDK build.
How does that sound?
TGEA 1.8 Beta Docs
#84
10/28/2008 (10:36 am)
Yey. Thanks Michael! But the fun part's still missing! :) I'll let you know when I find something weird.
#85
10/28/2008 (10:38 am)
@Konrad - Thanks! Btw, look for a reply to your e-mail soon. I'm way behind on responding to various contributions, but I'm addressing them as fast as I can between doc revisions. 
#86
And view that is still shows as TSE, then much of the content is based off of old docs. Shouldn't this either be updated- or pointed directly at the new docs? The new docs for getting started are wonderful, but the old ones- while *cough* reasonable, they are old and should be updated. (By new docs I mean those on the landing page which are included with the download package)
There are also a bunch of started tutorials that haven't gotten finished/polished. While not your fault, maybe a note at the top should be added to let others know of their incomplete state- or to add to them.
http://tdn.garagegames.com/wiki/TGEA/InstallVS2005 - This is the link that is followed when you click getting setup. It should really flow to the other getting started doc.
Granted, I haven't experimented much, but I could always just cut and paste your work from one doc, into the other. However seeing as that is your work, I wasn't sure that was how you wanted to handle that.
I also have yet to find a full listing of all the different server flags available in any official docs (Someone has got to wonder about it at some point.) I was able to find this information in the forums http://www.garagegames.com/index.php?sec=mg&mod=resource&page=view&qid=2444
and
http://www.garagegames.com/index.php?sec=mg&mod=resource&page=view&qid=2445
Both of which are generally useful information even if they are a bit long in the tooth.
I was having some serious problems running *.exe -server with modified preferences until I was showed these forum posts.
Those might even need to be updated as I don't see all of those functions/prefs being used any longer.
Thanks guys for all your hard work on updating the documentation of Torque. Torque documentation is starting to look like the AAA engine that Torque really is.
10/31/2008 (8:31 am)
TDN seems to be sadly, not getting some update love. Specifically TGEA. You can go to http://tdn.garagegames.com/wiki/Torque_Shader_EngineAnd view that is still shows as TSE, then much of the content is based off of old docs. Shouldn't this either be updated- or pointed directly at the new docs? The new docs for getting started are wonderful, but the old ones- while *cough* reasonable, they are old and should be updated. (By new docs I mean those on the landing page which are included with the download package)
There are also a bunch of started tutorials that haven't gotten finished/polished. While not your fault, maybe a note at the top should be added to let others know of their incomplete state- or to add to them.
http://tdn.garagegames.com/wiki/TGEA/InstallVS2005 - This is the link that is followed when you click getting setup. It should really flow to the other getting started doc.
Granted, I haven't experimented much, but I could always just cut and paste your work from one doc, into the other. However seeing as that is your work, I wasn't sure that was how you wanted to handle that.
I also have yet to find a full listing of all the different server flags available in any official docs (Someone has got to wonder about it at some point.) I was able to find this information in the forums http://www.garagegames.com/index.php?sec=mg&mod=resource&page=view&qid=2444
and
http://www.garagegames.com/index.php?sec=mg&mod=resource&page=view&qid=2445
Both of which are generally useful information even if they are a bit long in the tooth.
I was having some serious problems running *.exe -server with modified preferences until I was showed these forum posts.
Those might even need to be updated as I don't see all of those functions/prefs being used any longer.
Thanks guys for all your hard work on updating the documentation of Torque. Torque documentation is starting to look like the AAA engine that Torque really is.
#87
A good source for status and general documentation process information are the Michael's Blogs, and this thread.
Also, he is calling for active community participation. We not all can write docs, but for instance, if you see in TDN an uncomplete/unpolished/old/etc article, you can apply that note at the top (you mention it, and is actually practiced), as a little help for the process.
On a side note, you probably want to separate your paragraphs with a blank line, so its easier to read, and use the BB codes to create links on your posts (see the note below "Click here to learn how").
10/31/2008 (9:12 am)
David, Michael is currently working on those points you mention (you can see the new stylished TDN at the TGB section). However is so much work to do, that he has to somehow create a work scheme, and stick to it, or it would be an Impossible Mission(TM).A good source for status and general documentation process information are the Michael's Blogs, and this thread.
Also, he is calling for active community participation. We not all can write docs, but for instance, if you see in TDN an uncomplete/unpolished/old/etc article, you can apply that note at the top (you mention it, and is actually practiced), as a little help for the process.
On a side note, you probably want to separate your paragraphs with a blank line, so its easier to read, and use the BB codes to create links on your posts (see the note below "Click here to learn how").
#88
@David - Appreciate the feedback. I'll try to touch on each one of your points:
The Torque_Shader_Engine page is going to be phased out and replaced with TorqueGameEngineAdvanced. In general, I will be absorbing the best and most updated material on TDN and pushing it into the Official Docs.
The old material will be placed in a tucked away archive not meant for viewing. Essentially, I don't want duplicate information on TDN. The information found in the Official Documentation should be completely separate from TDN articles. For instance, the VS 2005 Article is going to be removed. The Getting Started section of the Official Docs is its replacement.
TDN will be used solely for community contributions, beta docs, and tutorials not related to the official documentation.
Thanks for the forum links! Good information =)
10/31/2008 (10:28 am)
@Novack - Thanks for providing a great response =)@David - Appreciate the feedback. I'll try to touch on each one of your points:
The Torque_Shader_Engine page is going to be phased out and replaced with TorqueGameEngineAdvanced. In general, I will be absorbing the best and most updated material on TDN and pushing it into the Official Docs.
The old material will be placed in a tucked away archive not meant for viewing. Essentially, I don't want duplicate information on TDN. The information found in the Official Documentation should be completely separate from TDN articles. For instance, the VS 2005 Article is going to be removed. The Getting Started section of the Official Docs is its replacement.
TDN will be used solely for community contributions, beta docs, and tutorials not related to the official documentation.
Thanks for the forum links! Good information =)
#89
10/31/2008 (10:30 am)
Oh, I forgot to mention. I'm going to be pushing more TGEA 1.8 Beta Docs this weekend, so be sure to check in if you are interested in reading more about the GFX2 and Resource Manager systems.
#90
11/01/2008 (6:58 am)
It would be cool if you could make the text wrap around in the right hand side pane so we dont have to use the scroll bar :)
#91
11/01/2008 (1:51 pm)
@metalliandy - Absolutely. That's why I'm converting all older doc pages to the TDN format, which is locked within a frame and wraps automatically.
#92
11/01/2008 (2:03 pm)
Michael, maybe sometime in the future would you consider creating a version or an automatic mirror of the help system for devices that do not support html frames and/or have a small screen space? These are mostly mobile devices of all kinds. It'd be really handy to be able to use a PDA or a PSP to read through TDN while on the go.
#93
11/02/2008 (2:08 am)
Thanks Michael :) 
#94
Please Dont hide it so far away we can not access it. Many times I still find myself referring to old documents
to get up to speed on the new documents.
I still use these really old Documents to this day!
BTW - Great job on all the Docs, I know its a really hard job!
11/03/2008 (7:37 am)
Quote:The old material will be placed in a tucked away archive not meant for viewing. Essentially, I don't want duplicate information on TDN.
Please Dont hide it so far away we can not access it. Many times I still find myself referring to old documents
to get up to speed on the new documents.
I still use these really old Documents to this day!
BTW - Great job on all the Docs, I know its a really hard job!
#95
I've sent a link to our TGEA developers, who are providing me with feedback on accuracy and content. All in all, it is content complete. That just leaves grammar and formatting.
In fact, when you get TGEA 1.8 and want to read new documentation, Gotchas is the first thing you should look at. You can even start preparing your existing projects for the porting process.
11/11/2008 (12:08 pm)
Hey everyone. I'm still adding content to TDN, but I'm bouncing from one article to another. However, I think I'm pretty much finished with the TGEA 1.8 Gotchas doc.I've sent a link to our TGEA developers, who are providing me with feedback on accuracy and content. All in all, it is content complete. That just leaves grammar and formatting.
In fact, when you get TGEA 1.8 and want to read new documentation, Gotchas is the first thing you should look at. You can even start preparing your existing projects for the porting process.
#96
11/11/2008 (12:31 pm)
Michael, this is really helpful! Thank you! Many things are still really blurry, but without this doc, I'd stand no chance in porting my game to 1.8. I really appreciate your work! 
#97
Mich, are you planning on updating the docs for tgea 1.8.1?
Specifically, I'm looking for in debth docs on the gfx system. The current docs gloss over it and are not too much help. I'm looking at porting some resources over, but am having a difficult time trying to figure out where functions are now being called from as a lot of them have moved.
In sceneObject.h, there are functions missing that were in the tge 1.5.x version. I have found a couple of the functions in the gfx folder, but it is a total and complete hassle to try to find them all in the scattered way they "seem" to be implemented now. (look up bsp tree in tge, then look it up in tgea. There is nothing there, and nothing to tell me how it's been changed or where to look)
03/28/2009 (2:22 pm)
Big bumpMich, are you planning on updating the docs for tgea 1.8.1?
Specifically, I'm looking for in debth docs on the gfx system. The current docs gloss over it and are not too much help. I'm looking at porting some resources over, but am having a difficult time trying to figure out where functions are now being called from as a lot of them have moved.
In sceneObject.h, there are functions missing that were in the tge 1.5.x version. I have found a couple of the functions in the gfx folder, but it is a total and complete hassle to try to find them all in the scattered way they "seem" to be implemented now. (look up bsp tree in tge, then look it up in tgea. There is nothing there, and nothing to tell me how it's been changed or where to look)
#98
There will be a substantial amount of Torque 3D docs that will apply to TGEA. For instance, Torque 3D's doc on the Sun object is currently 13 pages long without large screenshots. 7 of those pages will relate to both TGEA 1.8.1 and Torque 3D.
Another example is the SFX system. It will receive a thorough breakdown which will directly benefit users of both engines. There are more articles, but I will get into that after the 2nd Torque 3D doc release.
03/28/2009 (2:29 pm)
I do plan on circling back to TGEA 1.8.1.There will be a substantial amount of Torque 3D docs that will apply to TGEA. For instance, Torque 3D's doc on the Sun object is currently 13 pages long without large screenshots. 7 of those pages will relate to both TGEA 1.8.1 and Torque 3D.
Another example is the SFX system. It will receive a thorough breakdown which will directly benefit users of both engines. There are more articles, but I will get into that after the 2nd Torque 3D doc release.
#99
03/28/2009 (6:30 pm)
Can we maybe see about getting the t3d docs written up in some kind of book format? Something solid, and complete? this hunting and pecking for information sometimes is a bit frustrating and a big hitting point on your and GG docs.
#100
Torque 2D will get the same treatment, and if I can keep my intern longer I'm going to have him reorganize the TGEA docs in the same manner.
03/28/2009 (7:53 pm)
The docs will not be in book format, but they will be the most organized, polished, and complete set of Torque docs to date.Torque 2D will get the same treatment, and if I can keep my intern longer I'm going to have him reorganize the TGEA docs in the same manner.
Employee Michael Perry
ZombieShortbus
Anyone else?