Official Torque X Documentation Feedback

#41 Hi, I just started using torque x and though I am seeing fantastic potential in the engine I have to agree that the documentation is severely lacking.

I work on AAA titles professionally and am used to using proprietary tech with limited documentation. However while I may be crazy enough to want to make my own games after I get home from work I don't have the motivation to battle through undocumented code trying to figure out what x method does.

While I am impressed with the layout and philosophy of the torque x engine and think it offers a great platform for the indie developer the documentation is keeping me from recommending this engine to others.

As others are saying there are way to many instances were a tutorial asks us to copy and paste code without explaining why. Compound the lack of documentation with a slow moving forum and you have a serious barrier to entry.

While I am managing to move through the tutorials and pick up the engine I am spending way too much time figuring things out that should be in the docs. I would like to see:

- Tutorials that had deeper explanations as to why you where copying and pasting the code.

- More Tutorials on things like UI

- Updates that fix all of the bugs in the tutorials, there is nothing more frustrating then copying and pasting unexplained code only to have it fail to build.

- A doc that lists all of the Torque specific Methods, their expected parameters, return types, and explanation of what they do.

I'm really looking forward to working with the torque X engine and am hoping to see some docs that simplify the learning process.

Thanks.

#42 I've been working in TX for a while now (since beta/1.0). At this moment don't have any specific examples on how to improve the docs but here's some examples of my issues I've come across before I forget them:

- After mucking about with SceneObjects and thinking that Tilelayers had the same basic functionality as a normal SceneObject (due to the hierarchy) I soon discovered tileLayers did not want to handle collisionImages the same as SceneObjects. I couldn't find anything in the documentation stating that tilelayers like _each_ tile to have it's own poly collision image instead of a single large one (The editor is vague about this too).

- Using the Game state management sample as a base I'm using custom GUI classes and overlays (custom physics debug drawing) on top of TX's rendering. I searched for a while through the code and documentation to find out how to get access to the matrix transforms of the current scene so I can easily render my own custom classes in TX's scenegraph world space. Had to cobble together the transform from graphics widths, camera zooms, and sizes.

- Couldn't find much on the differences between PC and Xbox 360 development for TX. It's cross-platform, but I feel it's important to note subtle differences (ie loading large scenes on the 360 is much slower than PC).

- Couldn't find any information/advice in the documentation on which type of timing to use (fixed-step, variable step) and more detail on interpolation in TX, which works well if you let TX do it's thing, but once you want to mess with object positions (say a custom control component) things go wonky with no real explanation as to how to use it effectively.

#43 I spent a little time with TorqueX a few weeks back and managed to get through some of the basic tutorials without too many issues. Tonight I decided to start working on a game I've been planning for a while in TorqueX 2D. One the key features for what I'm planning requires that I'm able to modify the game tiles on the fly. So I created my new project, made some basic tile graphics, imported them into TorqueX builder and added an empty TileMap. I seemed to remember how that part works so all of that went smoothly. Next step was to figure out how to set a tile in a particular grid spot... whoosh... 4 hours have gone by and I still don't have a result. I'm guessing it'll only be half a dozen lines of code, but finding the right combination is proving next to impossible.

I'd like to reiterate what Matthew said recently...
- A doc that lists all of the Torque specific Methods, their expected parameters, return types, and explanation of what they do.
...and I'll add... including examples.

I'd consider this to be a standard requirement for an API like this, and as much as I'm dying to dig into all the cool stuff TorqueX has, I feel I can't even begin to work with it until something like this type of documentation exists. The .NET framework documentation in MSDN is a perfect example. It gives just enough to help me understand how all the objects fit together. When I created my first TorqueX project in Visual Studio my first instinct was to press F1 on one of the type names in code and was very disappointed to find nothing in there. It also took me quite a while to find the API doc that does exist in the TorqueX directory. At the very least I think that should be in the start menu along with the other help docs.

In the end 4 hours to figure out how to set a tile just isn't productive no matter how you look at it. I realise I could probably get help on the forums here but that would be painfully slow if I run into this kind of problem as often as it appears I will. I really hope you guys can catch up with this stuff sometime soon, because I fear if your TorqueX 3D API suffers the same problems, there are many other upcoming products out there that people will start turning to soon.

#44 Hehe, Ill be happy with some good 3d tutorials that are done in the approach done with the 2D stuff. I can slice up code and figure things out on my own, but things that could take me 30 minutes, end up taking days sometimes. The fps demo has given me a lot to learn from, but I usually have to understand the concept first, then slice away large portions of the code to figure out what it is really doing, then simplify it, and use it. Physics comes to mind here.

One approach that I always liked, was in addition to an api listing and the like, there was always a little code example, showing how it is used, etc. For instance, if you wanted to use the GroundControlComponent, it wouldnt be hard to add at the bottom of the class description, an example section that showed how an xml snippet of its usage for a derived implementation versus a stock one (and note that it is required to be in the xml to be used ). Just my two cents.

#45 Wow, those are some very detailed posts. Thanks!

I just settled in for my first day at the GG office, so now the real work is going to begin. Well, real work has been going on all along, so let's just say that productivity is going to skyrocket =)

Don't be afraid to rant on, even if you cover the same points as others. If I see a trend of requests, such as having more detailed explanations for code examples, I can better prioritize what to work on in the docs.

#46 I would make a quick suggestion too. Maybe the 2.0 api can be put up online, with a section per page in the api allowing people to add comments. Not only would you have the regular wiki , but you would also have a way for people to discuss the particular aspect in the api , or leave off helpful tidbits for others. Just a thought.

#47 Something like PHP.Net's documentation structure, David?

#48 @David

Yah, I assume you mean PHP.NET. I tend to like that format since it provides glimmers of information you just cant get from a pure api document. Just an idea, I know I would contribute a lot to that as I walk through the torquex 3d underbelly!

#49 Yup. I actually didn't mean to capitalize the 'n' in net and have a nasty habit of capitalizing PHP when mentioning it as a language. I really like the commentary feature of their docs as well. It is an extremely handy feature.

#50 As I was going over one of my favorite C++ books and asking myself what I loved about it the most. The answer came immediatly that the main thing that I loved about it when I was a beginner was the fact that it had a section in each chapter about common pitfalls. They sent at lengths to common problems and how to solve them. The classic example was the semicolon. Today its not an issue, but I would love to see those kind of things in the documentation.

Another example that happened recently was in the current documentation stated to add a new component go to Project -> Add new item.. Being a beginner in Torque I put it in the Torque section. Since the documentation didn't state that it should or shouldn't be in there since the Torque section was highlighted by default I assumed it needed to be there. Well, as soon as I built I got compile errors. It took me 4 days on the forums until someone pointed out to me that the component needed to be in the "Game" section.

For a beginner or maybe this is just me, but this would go perfectly in a common pitfalls section.

#51 @David Everhart - Mmmmm... php.net =). I will be looking at documentation for other technologies as inspiration. Torque Tech documentation will still have it's own look, feel, content, and format, but I will not ignore the awesome concepts used by other doc writers. I love the user feedback sections on phpt.net, and I really like how clean the Havok docs are. If anyone has any other examples of kick-ass documentation, please let me know.

@Chris - Pitfalls! Can't forget about those, as pointing out stumbling blocks is a big part of document generation process. Thanks for the suggestion! =)

#52 I was looking at the XML Deserialization section in the TX Docs. And when i was trying to implement a list (in the C# Types for Lists section). The explanation was ok, but it would be nice if we could just copy and paste a block of code in our game, build it and see the outcome. Then we just need to modify it to our requirements.

I've spend over 4 hours trying to import a list into TXB

And I still haven't managed to do it :(

#53 @Vishal - Sort of like what TGB docs have?

#54 Not really sure about TGB. I don't own it.
Does it have similar stuff? If so i might take a look at the docs.

#55 Well, we are trying to make sure from now on that all our sample code is part of the .html/.php pages. Which means you can highlight, copy, and paste. Eventually I'd like to put the "Copy code" button back in. This would copy all the code from a sample for you.

At the very least, I want to get away from the "screen shot" code. Then, of course, try and create a "final code" section at the bottom of the tutorials.

#56 Documentation Update

The New Documentation System is live!

Read my blog HERE

Here are the new TorqueX Links:
Main Landing Page

TorqueX Landing Page
TorqueX Official Documentation

#57 Update looks beautiful. Good jobs guys.

#58 @Michael

The2d Fantasy pack link on the TorqueX landing page leads to a page saying it is not availible :(

#59 @David - That's weird. I can see it when I click. Are you using Firefox or IExplore?

#60 You can click on the image below for a bigger one: (I am using IE 7, but shows same thing in firefox).