What you want in Documentation?

#21 I'm sure I will have more things to add, but as a recent owner (2 or 3 weeks), it's difficult to give much input. Some of this may be similar to what others have said, but I just wrote this up as my own thoughts were coming out.

I think having some specific game tutorials is still a good idea. People like the idea of having a working game in under an hour. One thing I think may help is to define the scope of the game at the beginning. Lay down a design at the beginning and have key bullet items listed. This way, you know what the eventual goal is, and you have a clear idea of what concepts will be covered. Saying, "...creating a very simple and basic fish themed game" does not really give any clue as to what the tutorial is attempting to cover.

It's extremely confusing finding example (old?) tutorials on-line but they don't relate at all to the current release. For example, a shooter tutorial is a good idea. I found what appears to be an older example, but the assets are no longer included in the installation. So, I plan to implement the shooter tutorial with fish spitting out some object. But having those original spaceship bitmaps will be nice to have. In any case, I just thought a shooter tutorial is a better idea than the fish one.

I definitely like having concepts and tend to find myself searching for a concept when trying to figure out something. I have looked more at the conceptual 'how-to' documentation than wading through a specific game tutorial to see something. In other words, I do really like the 'Features' section of the docs and right now, that is probably what gets the most reading.

I would like to see the underlined links show actual useful information. For example, the documentation may say something like 'click the object using the left mouse button....' with 'left' being an informational link. When you click on the text the information regarding 'left' has nothing to do with the context being described.

Fully describe parameters and options in the tutorials. When describing setting up a collision, describe all types of collisions and their meaning. The tutorial should not just say to select one and leave it at that. My first thought is, "well, what do the others do?" This is a great example of using an informational link with context sensitive information. It can describe all the choices. I spent too much time searching for a description of these. (See Fish Demo section 5.1 for an example of selecting NULL but no description of what anything means.)

I guess one thing I find is the tutorials are just so focused they lose sight of explaining the full context of the environment and the design portion. They basically explain the point they are trying to make and don't veer from going that little bit extra deeper (like the collision description in the previous paragraph).

As I've mentioned to Matt before, my Reference section pegs my CPU at 100% when I try to open it. I decided to update the computer to SP2 and all the latest XP updates (still using IE6) and it still pegs out but after around 40 seconds it finally opens up. The reference section is currently not very usable for me due to its sluggishness. But now that I have opened it up, I see it will be extremely helpful to have all of the functionality, parameters, etc. described.

There is a lot of terrific information on TDN. It will be nice to have the docs contain some of this extremely helpful information so we have it one place. I find myself too often searching forums and TDN over and over again trying to find certain things. If you don't bookmark it, it is often difficult to find it again.

I realize that's quite a lot and would take quite some work for a single person.

#22 I've noticed that the "layer management" section of the editor has no doc's in the included documentation.

#23 Thanks for the further great feedback... Steven S some great stuff.

#24 Also a note about the lack of definitions in the reference, everyone is completely correct in that. Unfortunately I got the auto-generation system done before we had a chance to get the descriptions updated... the night before the release I went through and updated all of the script methods for t2dSceneObject, but didn't have a chance to do any more.

Our end goal is to have all of those documented with examples.

#25 Thanks for the update Matthew. I'm sure that update alone will take quite some effort.

#26 The audio documentation in the TGB 1.5.1 reference is mostly missing.

#27 Just a few more thoughts...

@ Conor: I sincerely hope they integrate the VMPlayer resource before they put *too* much work into documenting the existing sound system.

@ Matthew: FWIW, I think it would be a real boon to the community for the Mini Platformer Tutorial be rid of wall climbing / ceiling-sticking bugs once and for all -- there have been various "solutions" posted about it, many of which I've tried, few of which have improved the situation, and none of which have been a good fix. If we could have an official GG word as to how to use TGB in this one small case, that would be a great jump start to many of us.

--clint

#28 @Clint, there is another platformer tutorial available on TDN called CustomPlatformer. Everything is working pretty well other than ramps and moving platforms at this stage. However, I have been working on it over the last few weeks and have a nearly bug free build ready.

I will do some more testing and upload the changes soon.

With regards to the specific problem, I would suggest that you read the giant forum post about it. There is a real problem with the way MiniPlatformer works. It is a good basis for a beginner learning, but it should not be used for any real games.

#29 Quick question... Seems like many find the highlighting functionality a hinderance. It seems like an easy fix would be to default the checkbox to unchecked, would that satisfy those that don't like it? (as well as being as an extremely easy thing for me to do).

#30 That could sure help. The highlighting seems to make it take way to long.
Just my 2 cents.
Jd

#31 Something that I would find helpful with the documentation is having something that I can print out and read while I am doing work within TGB. The problem that I have with online/offline documentation is the constant need to flip back and forth between the documentation and TGB. Of course this could be solved by getting a second monitor and having it right there, but for folks that don't have a lot of cash, this would be a big deal for them.

#32 This is really specific, but I'd like to see documentation for the FileSystem class. For instance, code that shows how to get the paths to all files in a specific folder (so I can load them). I tried using setCurrentDirectory, but Torque says the function doesn't exist. So a tutorial or more docs for those functions would be helpful.

Also more documentation on he audio stuff, like how to do 3D positioning and rate adjustment, would be helpful.

I agree with an earlier poster that each tutorial should be laser-focused: much like the Feature Tutorials from an older version of TGB.

#33 A printer friendly button has been on my list of 'want' for a while now... in fact someone who I share an office with just asked for that for the very same reason, he likes to print his tutorials out and go through them like that.

Great suggestions Vern... btw we still do have those feature tutorials :)

#34 I guess another good thing to document would be things that are broken, or that are advertised as being in TGE, but aren't.

For instance, GamePad support on the Mac. If I understand correctly, it's completely non-existent. Isn't there. So a "What isn't supported" document, detailing those things, plus if/when they are expected to be implemented, or if there is no plan to implement them anytime soon, would be helpful.

I think there are other differences between the Windows/Mac version of TGE too. For instance, I think you can use bindCmd to bind individual modifier keys, so that pushing Shift, for example, triggers an event. On the Mac this is not possible -- it has to be shift plus some other "normal" key.

So I guess what I'm suggesting is a "Differences between Mac and Windows versions" document, to avoid unnecessary hair-pulling when going between platforms. Or does such a document already exist somewhere?

#35 One more thing: documentation for t2dTextObject. (Added to 1.5.) Have no idea how to use it, but would really like to!

#36 I did a fast scan through the posts, so if this has already been covered, then I'm re-iterating:

I'd like to see more networking examples. The chess game was a great tutorial, but how about providing how (or best practice) with networking in other game examples. Maybe a quiz show? I only wish GG would just go ahead and include real-time networking into TGB.

How about code snips/gui screenshots of each TGB reference item? Like t2dTextObject - blah blah... then give a 1-5 liner code snip on how it can be used. I have struggled with the schedule command... I ended up using code from one of the GG members to make it work, yet I still don't understand why my one-liner doesn't kick in - maybe it was missing something that was a prerequisite.

Or even, how about, a coding best practices doc: When to use SimObject, or a "do not do this" example with datablocks. Hope this makes sense.

#37 Where are we at on all of this?
It's been a couple of months since the OP, and I was wondering when will we be seeing the newer documentation.

#38 Part of this was a pre-cursor to Torque 2.0 dev, before we announced Torque 2.0 dev. This input is also invaluable for any additional TGB documentation work. In fact right now we are working on getting the TGB reference more fleshed out. We also had a much more in-depth update pass on the existing docs and their compatibility with the latest version, as well as working on potential new docs. No promises, though know we are considering possibilities, and persuing some of them.

#39 Well I saw the newer documentation recently on the Torque X stuff and it looks like there is some movement in the right direction like the asking for feedback on a specific tutorial. That I do like to see.

#40 Where can I read more about Torque 2.0? I've heard the name mentioned a few times in the forums, but never seen any news or anything. Can anyone post a link?