Alternate Documentation?
by Carlos Ramos · in Torque Game Builder · 01/18/2009 (5:26 am) · 13 replies
I don't mean this as an insult to whoever created the documentation, but it sucks! For someone as new as myself, I can't find a single function or command using the search box...which then I assume doesn't exist in the document in the first place.
The few times that I do find something, it tells me jack-squat about how to use the command, or even what the command actually does. For example, I can't find any information in the document pertaining to literally none of the commands/functions in the script fleeMouse.cs that comes with the "mini-behavior tutorial". I mean how am I supposed to know what command to use if I can't even reference it up.
For the first two days I couldn't register my product, I can't access the Private-Forums, I can't access the TDN, and to understand how to use a command I have to search through all the tutorial scripts to see if I can find it. I'm not new to programming, I'm a network admin with the military, but quite frankly I'm starting to get pissed off.
The few times that I do find something, it tells me jack-squat about how to use the command, or even what the command actually does. For example, I can't find any information in the document pertaining to literally none of the commands/functions in the script fleeMouse.cs that comes with the "mini-behavior tutorial". I mean how am I supposed to know what command to use if I can't even reference it up.
For the first two days I couldn't register my product, I can't access the Private-Forums, I can't access the TDN, and to understand how to use a command I have to search through all the tutorial scripts to see if I can find it. I'm not new to programming, I'm a network admin with the military, but quite frankly I'm starting to get pissed off.
About the author
#2
Could you list some commands and functions you need help with? I'll post information directly and see what I can do to make them show up in the documentation more accurately.
@Jason - Considering I reply to nearly every documentation related question and comment, I'm curious as to which employee insulted you. I'm not sure where you are getting these interactions from, but I'm very open to criticism and suggestions about documentation.
Edit - Oh wait, now I remember. That was definitely a heated exchange in that blog. However, the best way to criticize the docs and have it worked on is in the feedback threads or my inbox.
01/18/2009 (12:14 pm)
@Carlos - We are still working on getting TDN fully up. A new bug seems to have popped up, so not everyone can access for some reason. It is running, and a lot of us are in, but we have to drill down some more.Could you list some commands and functions you need help with? I'll post information directly and see what I can do to make them show up in the documentation more accurately.
@Jason - Considering I reply to nearly every documentation related question and comment, I'm curious as to which employee insulted you. I'm not sure where you are getting these interactions from, but I'm very open to criticism and suggestions about documentation.
Edit - Oh wait, now I remember. That was definitely a heated exchange in that blog. However, the best way to criticize the docs and have it worked on is in the feedback threads or my inbox.
#3
I don't know your email, it's not in the profile, but I did add you to my IM list. Back when I had more time, there were many people that were given help and feedback when they were new to TGB. Most of them gave up after a bit. Considering TGB is *the* entry-level Torque product, it would make sense to really beef up the documentation there. Most of what I learned about TorqueScript came from buying The Game Programmers Guide To Torque (AKA: the not-free manual).
Honestly, Carlos, forget about behaviors for a bit, learn how TGB *works* first. Skip the editor and just dig into the default scripts for a while. You're more than welcome to email me any time that I'm online. If I don't reply immediately, just be patient.
01/18/2009 (2:48 pm)
Michael,I don't know your email, it's not in the profile, but I did add you to my IM list. Back when I had more time, there were many people that were given help and feedback when they were new to TGB. Most of them gave up after a bit. Considering TGB is *the* entry-level Torque product, it would make sense to really beef up the documentation there. Most of what I learned about TorqueScript came from buying The Game Programmers Guide To Torque (AKA: the not-free manual).
Honestly, Carlos, forget about behaviors for a bit, learn how TGB *works* first. Skip the editor and just dig into the default scripts for a while. You're more than welcome to email me any time that I'm online. If I don't reply immediately, just be patient.
#4
01/18/2009 (5:27 pm)
I have just received that book, is it beneficial to TGB even though it seems aimed at TGE?
#5
Well:
Michael Perry
michaelp@garagegames.com
mich.perry@gmail.com
AIM: Loco Peffe
GTalk: mich.perry@gmail.com
01/18/2009 (8:56 pm)
Crap. I guess it's not listed anymore =/Well:
Michael Perry
michaelp@garagegames.com
mich.perry@gmail.com
AIM: Loco Peffe
GTalk: mich.perry@gmail.com
#6
And the TileSets def could use more explainations. I can make a tileset, have one running in the game, just no idea what all them options are for like Name. I cant seem to get the name in the script from it, tryied to make a pacman clone, and set a bunch of wall tiles, gave the tileset a colision option, made a script, no idea how to tell it to look at what its colliding with and what to do with it :P oh well more to dig into with it.
01/18/2009 (11:55 pm)
I agree with the new doc option :) Mostly because while the Tutoirals are kinda good starts, thier also not detailed enough inalota thier samples. Thier behaviour scripts are good examples. I would like to Convert that mouse Flee to Mouse Follow, not like the one thats thier that more or less is as fast as the mouse, something you move your mouse and it has a set speed that moves for it, not just bang its thier :)And the TileSets def could use more explainations. I can make a tileset, have one running in the game, just no idea what all them options are for like Name. I cant seem to get the name in the script from it, tryied to make a pacman clone, and set a bunch of wall tiles, gave the tileset a colision option, made a script, no idea how to tell it to look at what its colliding with and what to do with it :P oh well more to dig into with it.
#7
@Michael - Thanks. To be honest, if most of the lines in the tutorial where commented, I would pick it up faster than anything. The problem comes when a command is being used and I have no idea why.
01/19/2009 (4:40 am)
Thanks for the advice J, I guess my problem is I'm more stubborn than anything when it comes to learning how commands work.@Michael - Thanks. To be honest, if most of the lines in the tutorial where commented, I would pick it up faster than anything. The problem comes when a command is being used and I have no idea why.
#8
Here is a fine example of incomplete documentation:
That is straight out of TDN. I am pretty sure that I know what this GUI control is, but if someone new were to come in and see what appears to be a question rather than a statement, don't you think they would be a little confused? "A specialized form of an array for creating tree structures?" Are you asking if this control is a specialized form of an array for creating tree structures? Or, are you making a statement?
Or how about this one:
This one (below) contains a decent description, but the usage section is blank, and therefore incomplete:
I understand that the online documentation has many authors, as it is Wiki (I disagree with using Wiki for tech docs like this, but that is another story). This is the torque developer network after all. It is a collaborative effort, and I understand that, but if you are going to allow us, the customer, write your documentation for you (directed at GG) then you are going to have a big mess on your hands. The core documentation (not just overviews and short tutorials, but the technical documentation) should be written by the developer (maybe a tech writer sitting by the developer). I know what you are thinking, 'why doesn't he just get the doxygen documentation?'. Well that would be fine if the code was commented in a way that explains every detail of a class and method, but it does not. Doxygen is only as good as the programmer who commented the code.
The offline documentation is worse because it doesn't really list anything useful in the reference and the only meaningful documentation is really in what appears to be tutorials (in the offline documentation). These are handy tutorials, but we are looking for a list of controls, functions, classes, and a very detailed description of what they do and the usage statements. This should have been done as the engine was being written, but apparently that part was suspended until the engine was complete (or at least it appears that way).
I think you all should seriously think about hiring an actual technical writer to document your system. Not having complete and comprehensive documentation only results in frustration, hours of wasted research time, and folks seeking other engines that contain better documentation.
04/18/2009 (10:04 am)
Well, it's 4 months later and the documentation hasn't improved. I think I may start documenting everything that I am doing in detail so that I can put together a decent set of documentation if we can't get one from the creators of the tools we use. Another problem is this new site. It is the most horrid site for finding information now. The old site was lacking, but the search was a lot better. This site's search is terrible. I am not sure who made the command decision to redesign the site, but in retrospect, it was a bad bad move (IMO).Here is a fine example of incomplete documentation:
Quote:
CreatorTree
Description: A subclass of GuiArrayCtrl. A specialized form of an array for creating tree structures?
Reference: [Documentation]
Usage Example: None
That is straight out of TDN. I am pretty sure that I know what this GUI control is, but if someone new were to come in and see what appears to be a question rather than a statement, don't you think they would be a little confused? "A specialized form of an array for creating tree structures?" Are you asking if this control is a specialized form of an array for creating tree structures? Or, are you making a statement?
Or how about this one:
Quote:
GuiAviBitmapCtrl
Description:
Reference:
Usage Example:
This one (below) contains a decent description, but the usage section is blank, and therefore incomplete:
Quote:
GuiBitmapButtonCtrl
Description: The GuiBitmapButtonCtrl is used whenever you want to use a button that was created in a graphics program like Photoshop. You need to create four copies of the image located in the same directory and named button_h, button_d, button_i, and button_n. These images represent the normal (_n), hilight (_h), depressed (_d), and inactive (_i) states. You tell the control which bitmap files to use with the bitmap field, setting it to the directory path of the bitmap files. Note that in the "bitmap" field you should not use any file suffixes; thus, if your button image files are named myButton_h.png, myButton_d.png, myButton_i.png, and myButton_n.png, then the "bitmap" field of the GuiBitmapButtonCtrl should just be set to "\directoryPath\myButton". You can save your buttons as either *.png or *.jpg files depending on your need for transparency.
Reference:
Usage Example:
I understand that the online documentation has many authors, as it is Wiki (I disagree with using Wiki for tech docs like this, but that is another story). This is the torque developer network after all. It is a collaborative effort, and I understand that, but if you are going to allow us, the customer, write your documentation for you (directed at GG) then you are going to have a big mess on your hands. The core documentation (not just overviews and short tutorials, but the technical documentation) should be written by the developer (maybe a tech writer sitting by the developer). I know what you are thinking, 'why doesn't he just get the doxygen documentation?'. Well that would be fine if the code was commented in a way that explains every detail of a class and method, but it does not. Doxygen is only as good as the programmer who commented the code.
The offline documentation is worse because it doesn't really list anything useful in the reference and the only meaningful documentation is really in what appears to be tutorials (in the offline documentation). These are handy tutorials, but we are looking for a list of controls, functions, classes, and a very detailed description of what they do and the usage statements. This should have been done as the engine was being written, but apparently that part was suspended until the engine was complete (or at least it appears that way).
I think you all should seriously think about hiring an actual technical writer to document your system. Not having complete and comprehensive documentation only results in frustration, hours of wasted research time, and folks seeking other engines that contain better documentation.
#9
Torque 2D will get the same treatment: a full rewrite. The other engines' documentation will be cleaned up and updated.
04/18/2009 (10:32 am)
Quote:Well, it's 4 months later and the documentation hasn't improved
Quote:I think you all should seriously think about hiring an actual technical writer to document your system.@Derik - There is an official documentation writer: me.
Quote:This should have been done as the engine was being writtenI have been focusing on Torque 3D and iTorque for the past 4 months, writing new sections as modules are completed. That has me tasked out to the max, as I have been writing Torque 3D's full documentation from scratch. Once that goes out the door, I can then cycle back and improve the docs for the rest of the engines.
Torque 2D will get the same treatment: a full rewrite. The other engines' documentation will be cleaned up and updated.
#10
I've setup a dokuwiki on my machine. Then every time I go searching for some piece of documentation, when I find my answer I update my wiki.
That way I can keep track of every issue I encounter, and its quick for me to look up again.
One day I'll get around to formatting this and posting it back to GG or writing some tutorials or something.
Actually, the GG documentation isn't really that bad. You should try making mobile games when all you have to go off is a Javadoc in Japanese (yes, that's what I'm doing now).
04/21/2009 (3:02 am)
Here's what I've done.I've setup a dokuwiki on my machine. Then every time I go searching for some piece of documentation, when I find my answer I update my wiki.
That way I can keep track of every issue I encounter, and its quick for me to look up again.
One day I'll get around to formatting this and posting it back to GG or writing some tutorials or something.
Actually, the GG documentation isn't really that bad. You should try making mobile games when all you have to go off is a Javadoc in Japanese (yes, that's what I'm doing now).
#11
I think the product looks great, but I cant even get past tutorial 1. It asks me to create a new level, selecting File New Level, and all I have is File New Scene. I tried to look up "scenes" in the help and couldn't find anything.
May give DarkBasic a try.
Regards
i
04/22/2009 (5:11 pm)
Hi,I think the product looks great, but I cant even get past tutorial 1. It asks me to create a new level, selecting File New Level, and all I have is File New Scene. I tried to look up "scenes" in the help and couldn't find anything.
May give DarkBasic a try.
Regards
i
#12
04/22/2009 (5:36 pm)
Scene is interchangeable with level. A game's level consists of a scene and sceneObjects. The TGB docs will be updated later on to reflect the latest build. 
Torque 3D Owner Jason Ravencroft
When I brought up the state of the documentation, I was just insulted by a GG employee.