Official iT2D Documentation Feedback
by Michael Perry · in iTorque 2D · 09/27/2008 (11:01 am) · 102 replies
======================================================================
This Thread Is The Official Documentation Feedback Area For ALL Versions of iTorque 2D
If you want to quick search for all iTGB Doc Updates, perform a keyword search in your browser for
"Documentation Update:"
======================================================================
Hey everyone. It's about time we have a central thread for iT2D users to post their feedback in regard to documentation.
We have similar threads going on in the other forums forum, and so far the feedback has been overwhelmingly positive, constructive, and very helpful to the doc writers...so let's keep that going with iT2D=)
Purpose of the Thread:
- Provide a central thread for iT2D users to post their thoughts, suggestions, and criticisms about documentation.
Targets:
- Official documentation provided by TorquePowered, TDN articles, and user submitted docs/tutorials.
Suggestions for Posts:
- What is the #1 thing you would like added to the official docs?
- What area of the docs do you think needs the most work?
- What do you see in other tech docs, be it for other Torque engines or non-Torque tech, that you think would be beneficial to have in the docs?
- What are your feeling on TDN vs how the current official docs are presented?
- Bring attention to resources, tutorials, articles, or community member submissions you think should be merged into the official docs
...etc, etc
So, the overall concept of this thread is pretty simple. This is your chance to talk until your face turns blue about what you want from the docs.
Be as clear, descriptive, and specific as you can!
This Thread Is The Official Documentation Feedback Area For ALL Versions of iTorque 2D
If you want to quick search for all iTGB Doc Updates, perform a keyword search in your browser for
"Documentation Update:"
======================================================================
Hey everyone. It's about time we have a central thread for iT2D users to post their feedback in regard to documentation.
We have similar threads going on in the other forums forum, and so far the feedback has been overwhelmingly positive, constructive, and very helpful to the doc writers...so let's keep that going with iT2D=)
Purpose of the Thread:
- Provide a central thread for iT2D users to post their thoughts, suggestions, and criticisms about documentation.
Targets:
- Official documentation provided by TorquePowered, TDN articles, and user submitted docs/tutorials.
Suggestions for Posts:
- What is the #1 thing you would like added to the official docs?
- What area of the docs do you think needs the most work?
- What do you see in other tech docs, be it for other Torque engines or non-Torque tech, that you think would be beneficial to have in the docs?
- What are your feeling on TDN vs how the current official docs are presented?
- Bring attention to resources, tutorials, articles, or community member submissions you think should be merged into the official docs
...etc, etc
So, the overall concept of this thread is pretty simple. This is your chance to talk until your face turns blue about what you want from the docs.
Be as clear, descriptive, and specific as you can!
About the author
Programmer.
#62
I guess the docs needs a good refreashing:
1) Better organise the doc: the exemples / tutorials always asks me to do stuff I don't know about because the info is at the end in the Component Tutorials.
2) More info on the basic workflow, integration with Xcode
3) Can we have info about the GUI editor ?
4) Can we have sample tutorials / projects convering the whole creation of a game, and not just a level. I'd love to see a tutorial for a sample game with a splash screen > Main Menu > Level 1 > Level 2 > Ending, because I can't find good material to link scenes together sadly.
5) Aslo need a refreash with the new line of products as the different names for the same product can be confusing
6) More info about optimising assets for mobile device use
7) And that's it for now :)
01/30/2011 (7:05 am)
I've just finished reading the whole iTorque documentation.I guess the docs needs a good refreashing:
1) Better organise the doc: the exemples / tutorials always asks me to do stuff I don't know about because the info is at the end in the Component Tutorials.
2) More info on the basic workflow, integration with Xcode
3) Can we have info about the GUI editor ?
4) Can we have sample tutorials / projects convering the whole creation of a game, and not just a level. I'd love to see a tutorial for a sample game with a splash screen > Main Menu > Level 1 > Level 2 > Ending, because I can't find good material to link scenes together sadly.
5) Aslo need a refreash with the new line of products as the different names for the same product can be confusing
6) More info about optimising assets for mobile device use
7) And that's it for now :)
#63
General Doc Work: Create a revised documentation layout. No more lingering TGB specific docs. This may shrink some of the content, but sometimes bad docs are worse than no docs. If a guide is pertinent, it will be kept. In general the layout might change again.
Shooter: Shows how to create an auto-scrolling shooter, similar to R-Type. This will be a clean port of the Torque 2D BehaviorShooter project, with assets reduced and optimized for iT2D. Will utilize a "thumb stick" for controls and as many iT2D features as possible.
iOS Series: Series on how to use each iOS feature exposed (input, music player, movie, etc).
Rainy Day: Convert T2D tutorial to an iOS friendly version. What's currently available online should not be there. I'm not sure why that version made it in, but the iT2D version is nearly finished. Utilizes accelerometer and touch for input, plus a few extra features added in to spice up the demo.
iAquarium*: Shows how to create a fish aquarium simulator. The base tutorial is already up, it just needs a review to make sure it still works. I also want to add a section for input reaction, such as tapping on the screen to scare the fish.
C++ Behaviors: Explains how to create a few behaviors in C++ and link them to TorqueScript. Example code already exists, but is not covered anywhere in the docs.
FAQ: Documentation containing answers to a long list of frequently asked questions based on past user experience and community posts.
What do you think? Useful? Something missing?
02/01/2011 (4:05 pm)
Goals for 1.4.1 Docs
I proposed the following list of tutorials for 1.4.1 and beyond. I would like to get all of these in, but if something can't be completed it will be rolled into the next version. It should be noted that most of these can be shipped as completed demos as well.General Doc Work: Create a revised documentation layout. No more lingering TGB specific docs. This may shrink some of the content, but sometimes bad docs are worse than no docs. If a guide is pertinent, it will be kept. In general the layout might change again.
Shooter: Shows how to create an auto-scrolling shooter, similar to R-Type. This will be a clean port of the Torque 2D BehaviorShooter project, with assets reduced and optimized for iT2D. Will utilize a "thumb stick" for controls and as many iT2D features as possible.
iOS Series: Series on how to use each iOS feature exposed (input, music player, movie, etc).
Rainy Day: Convert T2D tutorial to an iOS friendly version. What's currently available online should not be there. I'm not sure why that version made it in, but the iT2D version is nearly finished. Utilizes accelerometer and touch for input, plus a few extra features added in to spice up the demo.
iAquarium*: Shows how to create a fish aquarium simulator. The base tutorial is already up, it just needs a review to make sure it still works. I also want to add a section for input reaction, such as tapping on the screen to scare the fish.
C++ Behaviors: Explains how to create a few behaviors in C++ and link them to TorqueScript. Example code already exists, but is not covered anywhere in the docs.
FAQ: Documentation containing answers to a long list of frequently asked questions based on past user experience and community posts.
What do you think? Useful? Something missing?
#64
02/01/2011 (4:09 pm)
Depending on whether we can get the additional writer(s) I've requested, we might be able to do a full reference push for iT2D...similar to what we did with T3D. If you are unfamiliar with the T3D Reference Project, check out this blog. It is in no way a small task. iT2D is not as complex at T2D, but a full reference pass is more work than a single person working full time can handle in time for a 1.4.1 release. However, it's on my proposal for a 2011 enhancement. 
#65
02/01/2011 (6:59 pm)
One thing I'd like to suggest is something of how to do a scroller. There was at one point a ninja game tutorial. Heck even a basic just make a map move around on the screen would be good.
#66
I don't know how the actual tutorials looks like, but I'd really love one on building a full game with:
splash screen > menus > loading screen (assets management) > level > post levels action (loading level 2, going back to main menu, etc).
02/02/2011 (5:47 am)
@Michael Perry: sounds very good.I don't know how the actual tutorials looks like, but I'd really love one on building a full game with:
splash screen > menus > loading screen (assets management) > level > post levels action (loading level 2, going back to main menu, etc).
#67
Next step towards simplification after this in my eyes would not be documentation but further automation of elements such as image packing and compression. If the assets are in Torque and we even have fine grain control of datablocks, surely torque can calculate efficient image maps automatically and perform automatic compression, perhaps with an optimise button along the top bar.
02/03/2011 (12:26 pm)
Seem good to me!Next step towards simplification after this in my eyes would not be documentation but further automation of elements such as image packing and compression. If the assets are in Torque and we even have fine grain control of datablocks, surely torque can calculate efficient image maps automatically and perform automatic compression, perhaps with an optimise button along the top bar.
#68
What you see in the preview release is the new setup. Restructuring the TOC, adding more comprehensive TorqueScript overview (full syntax, methodology, basic samples), updating introduction and setup to reflect current tech, and so on. Everything under the Editors section is legacy docs. That is all being removed or updated to better fit iTorque 2D 1.4.1. No more legacy TGB documentation!
I'm open to your feedback on the new layout and how the new script docs are shaping up.
02/11/2011 (7:43 pm)
You can preview the new documentation setup in the 1.4.1 preview release (available for download now). Very important things to note...In fact, so important:Very Important
The docs are not complete for 1.4.1What you see in the preview release is the new setup. Restructuring the TOC, adding more comprehensive TorqueScript overview (full syntax, methodology, basic samples), updating introduction and setup to reflect current tech, and so on. Everything under the Editors section is legacy docs. That is all being removed or updated to better fit iTorque 2D 1.4.1. No more legacy TGB documentation!
I'm open to your feedback on the new layout and how the new script docs are shaping up.
#69
I tried to use the drag code in game.cs but it worked only in iTGB preview so I tried to compile the Shooter game (working on preview) but the dPad drag movement doesn't work both on Simulator and iPhone (this make the game unplayable) however the fire button worked both in Simulator and Device.
02/25/2011 (3:16 pm)
One thing about Shooter project that come with iTorque2D 1.4.1I tried to use the drag code in game.cs but it worked only in iTGB preview so I tried to compile the Shooter game (working on preview) but the dPad drag movement doesn't work both on Simulator and iPhone (this make the game unplayable) however the fire button worked both in Simulator and Device.
#70
This is handled out of the box for 1.4.1 final.
02/25/2011 (3:31 pm)
This is likely because the multi-touch flag is not enabled on the project. We found there was a bug in the editor scripts that was not saving settings and that some projects in Xcode were not using the editor flags. Check to see if the $pref::iDevice::UseMultitouch variable is set to true. If it is not, then that would be the problem.This is handled out of the box for 1.4.1 final.
#71
The movement pad doesn't want to work (both in the simulator and iDevice).
I have to change some source code with Xcode?
02/26/2011 (9:05 am)
I tried to check "MultiTouch Support" but nothing changed. I also tried to write $pref::iDevice::UseMultitouch = true; in game.cs but nothing changed.The movement pad doesn't want to work (both in the simulator and iDevice).
I have to change some source code with Xcode?
#72
02/26/2011 (9:54 am)
@Andrea - Ok. Well I'm not quite sure what is going on, but the version of the demo you are working with is not complete. It was just meant to be a preview of what the genre would be. I don't have this bug on my side, so it's likely the demo didn't ship with the full controls enabled. I wouldn't spend anymore time on it until I ship the full version. 
#73
In the Reference/TGB Reference section of the documentation the methods/callbacks/fields for classes are no longer nested like they were in TGB 1.7.4, meaning once you click on a class (such as t2dSceneObject) you're presented with the entire list and their descriptions in the right panel of the documentation website. This makes it very hard to find stuff. For example if I wanted to find the header for the onCollision callback in TGB 1.7.4 I could click the plus beside t2dSceneObject, then click the plus beside callbacks and there was a list of all callbacks in the left panel. Then clicking onCollision would bring up the header on the right.
With the iT2D 1.4.1 documentation the list is so huge it's impossible to find something unless you already know what it's called. For students and beginners to the engine, having all the methods, callbacks and field separated and nested correctly was an easy way to browse the reference and learn what functions are available.
In the stringFunction section strChr is listed twice, without any explanation as to what it does. Many other string functions have no explanation, just a header.
The getWord function is missing from the stringFunctions list. This is an essential function in TorqueScript!
TGB reference should be renamed to something more descriptive - like TorqueScript functions list.
TGB Glossary should be renamed Torque Glossary (as the TGB title is no longer in use).
Lastly, putting the TorqueScript overview and TorqueScript reference right at the end of the functions list in the reference section makes it very unlikely that new users will ever see them. These sections should be moved out of this area and given more visibility.
03/05/2011 (6:18 pm)
Documentation problems with 1.4.1 preview:In the Reference/TGB Reference section of the documentation the methods/callbacks/fields for classes are no longer nested like they were in TGB 1.7.4, meaning once you click on a class (such as t2dSceneObject) you're presented with the entire list and their descriptions in the right panel of the documentation website. This makes it very hard to find stuff. For example if I wanted to find the header for the onCollision callback in TGB 1.7.4 I could click the plus beside t2dSceneObject, then click the plus beside callbacks and there was a list of all callbacks in the left panel. Then clicking onCollision would bring up the header on the right.
With the iT2D 1.4.1 documentation the list is so huge it's impossible to find something unless you already know what it's called. For students and beginners to the engine, having all the methods, callbacks and field separated and nested correctly was an easy way to browse the reference and learn what functions are available.
In the stringFunction section strChr is listed twice, without any explanation as to what it does. Many other string functions have no explanation, just a header.
The getWord function is missing from the stringFunctions list. This is an essential function in TorqueScript!
TGB reference should be renamed to something more descriptive - like TorqueScript functions list.
TGB Glossary should be renamed Torque Glossary (as the TGB title is no longer in use).
Lastly, putting the TorqueScript overview and TorqueScript reference right at the end of the functions list in the reference section makes it very unlikely that new users will ever see them. These sections should be moved out of this area and given more visibility.
#74
03/05/2011 (6:46 pm)
There is no support for iPad development in the iT2D 1.4.1 documentation. Searching for iPad shows 1 hit, which simply states the iPad's resolution. Specific instructions on how to set up your target in Xcode for iPad deployment, and universal app deployment should be included.
#75
03/06/2011 (9:41 am)
Thanks Conor! Great feedback.
#76
Rather than uploading in one huge chunk, I'm pushing the new docs online in small pieces. The first round is up. Not all of them are complete, but they will be by the time 1.4.1 goes up. The list of known issues is too large to post, but know that I am working on the docs and updating them very frequently. Some highlights worth mentioning:
- New Rainy Day Tutorial: More progress, but not finished
- New FAQ Page: First iteration is up, but not finished. This will be an ongoing doc
- New Editors Section: This is replacing the old "Feature" tutorial. This section only has four pieces at the moment (Static Sprites, Animated Sprites, Collision and Scrollers), but I'm knocking these out at 1 or 2 a day
- TorqueScript Section: I'm porting over the best of the Torque 3D script documentation and will be adding more iTorque 2D specific stuff
03/10/2011 (5:58 pm)
Attention All
New docs are streaming in: iTorque 2D Online DocumentationRather than uploading in one huge chunk, I'm pushing the new docs online in small pieces. The first round is up. Not all of them are complete, but they will be by the time 1.4.1 goes up. The list of known issues is too large to post, but know that I am working on the docs and updating them very frequently. Some highlights worth mentioning:
- New Rainy Day Tutorial: More progress, but not finished
- New FAQ Page: First iteration is up, but not finished. This will be an ongoing doc
- New Editors Section: This is replacing the old "Feature" tutorial. This section only has four pieces at the moment (Static Sprites, Animated Sprites, Collision and Scrollers), but I'm knocking these out at 1 or 2 a day
- TorqueScript Section: I'm porting over the best of the Torque 3D script documentation and will be adding more iTorque 2D specific stuff
#77
As discussed in IRC:
Introduction issues:
1. iTorque Technology section spelling error spelling "Torque Script" when you refer to it as 1 word every where else.
2. "(16,32,64,512, etc)" Should have spaces between the numebrs and the commas
3. You state "There are other "gotchas" you should remember when developing a game for a mobile device. " but don't list them
4. Contents title at top in the box has a blank line above it. Should be aligned to top of box.
5. "o The iPhone 4 will feature double the resolution" ... It's out so you can cahnge it to "DOES feature"
Engine section:
6. "and optimize game play code using native language. " just doesn't sound right (the native language part).
7. "Again, do not be intimidated. " ... You did not previously state not to be intimidated.
8. "If you wish to start working with the engine, you can do so whenever you " ... dont need a comma
9. "script, save, then run" grammatical error. should be save it
10. Same line as 9, need to make it clear people have to RESTASRT the game.
11. "of iPhone development, then " ... the last line in Conclusion. It should be "and" instead of a comma, I think.
03/10/2011 (6:58 pm)
... you sure do ask for a lot Mich...As discussed in IRC:
Introduction issues:
1. iTorque Technology section spelling error spelling "Torque Script" when you refer to it as 1 word every where else.
2. "(16,32,64,512, etc)" Should have spaces between the numebrs and the commas
3. You state "There are other "gotchas" you should remember when developing a game for a mobile device. " but don't list them
4. Contents title at top in the box has a blank line above it. Should be aligned to top of box.
5. "o The iPhone 4 will feature double the resolution" ... It's out so you can cahnge it to "DOES feature"
Engine section:
6. "and optimize game play code using native language. " just doesn't sound right (the native language part).
7. "Again, do not be intimidated. " ... You did not previously state not to be intimidated.
8. "If you wish to start working with the engine, you can do so whenever you " ... dont need a comma
9. "script, save, then run" grammatical error. should be save it
10. Same line as 9, need to make it clear people have to RESTASRT the game.
11. "of iPhone development, then " ... the last line in Conclusion. It should be "and" instead of a comma, I think.
#78
"The official documentation is divided into multiple sections, each of which contains information related to specific subject."
should be "a specific subject" or "specific subjects"
03/11/2011 (5:23 am)
The landing page has an error:"The official documentation is divided into multiple sections, each of which contains information related to specific subject."
should be "a specific subject" or "specific subjects"
#79
03/11/2011 (5:29 am)
Landing page states "there are key articles you should read through first" and then sends you to the introduction but doesn't list the key articles.
#80
03/11/2011 (5:38 am)
When I hover over Introduction there is a rollover or something that appears above my mouse but it is under the header bar so I cant read it. 
Torque Owner Jeremy R. Mahon
Default Studio Name
Also, while reading the installation documentation for iTorque in the provided docs, iTorque was referred to (at several points) as "TGEA" (which I know what it stands for) which I believe to be a slight editorial error. Just my 2 cents. :D