Why is the reference documentation so lacking
by Derry Bryson · in Torque Game Engine · 07/31/2007 (9:42 pm) · 25 replies
Sorry, but i just don't understand. No offense to the community members here that contributed documentation intended.
Why is the reference documentation so lacking for TGE. As a programmer, I understand that tutorials, howto's, etc. are hard documents to write, but reference documents are not. Reference documents are tedious, but not actually hard to write, in fact, given the right tools they even write themselves sometimes. Why isn't there complete documentation for the global variables, functions, datablocks, and objects exposed in TorqueScript provided by Garage Games? Why do I have to rely on documentation provided by third parties who are only guessing in many cases?
Please help me to understand. I have placed this in a private section, so it will not affect your sales, and I have purchased your product.
Why is your documentation so lacking?
Why is the reference documentation so lacking for TGE. As a programmer, I understand that tutorials, howto's, etc. are hard documents to write, but reference documents are not. Reference documents are tedious, but not actually hard to write, in fact, given the right tools they even write themselves sometimes. Why isn't there complete documentation for the global variables, functions, datablocks, and objects exposed in TorqueScript provided by Garage Games? Why do I have to rely on documentation provided by third parties who are only guessing in many cases?
Please help me to understand. I have placed this in a private section, so it will not affect your sales, and I have purchased your product.
Why is your documentation so lacking?
#22
08/17/2007 (10:31 pm)
I have a lot on my plate these days so I can't give any sort of timelines but I can let you know that there has been a lot of discussion about the documentation in the office lately =)
#23
sometimes
the
purpose
of
variables, block of codes
and methods
are
very lacking
I thought torque is mainly meant for teaching.. not for making big games that sells milions of copies.
Therefore documentation in the engine source code will help beginners a lot.
12/25/2007 (10:15 am)
Too little torque engine code documentation.sometimes
the
purpose
of
variables, block of codes
and methods
are
very lacking
I thought torque is mainly meant for teaching.. not for making big games that sells milions of copies.
Therefore documentation in the engine source code will help beginners a lot.
#24
Yeah, I know, I could have worked for GG.
Sorry, couldn't resist the joke. ;-)
Don't expect any improvement on documentation.
12/25/2007 (11:33 am)
Quote:Why is the reference documentation so lacking?Because!
Yeah, I know, I could have worked for GG.
Sorry, couldn't resist the joke. ;-)
Don't expect any improvement on documentation.
#25
Take Adobe's documentation for Flash. Here is an excerpt.
random (Math.random method)
public static random() : Number
Returns a pseudo-random number n, where 0 <= n < 1. The number returned is called a "pseudo-random" number because it is, technically, calculated in an undisclosed manner.
Availability: ActionScript 1.0; Flash Player 5 - In Flash Player 4, the methods and properties of the Math class are emulated using approximations and might not be as accurate as the non-emulated math functions that Flash Player 5 supports.
Returns
Number - A number.
-------------------------------------------------------
Example
The following example outputs 100 random integers between 4 and 11 (inclusively):
function randRange(min:Number, max:Number):Number {
var randomNum:Number = Math.floor(Math.random() * (max - min + 1)) + min;
return randomNum;
}
for (var i = 0; i < 100; i++) {
var n:Number = randRange(4, 11)
trace(n);
}
-------------------------------------------------------
Now anyone here would look at that and know how to use the function.
01/08/2008 (5:52 am)
In my opinion, the biggest thing that the documentation needs are examples. For each method, function, etc, There should be a very small example.Take Adobe's documentation for Flash. Here is an excerpt.
random (Math.random method)
public static random() : Number
Returns a pseudo-random number n, where 0 <= n < 1. The number returned is called a "pseudo-random" number because it is, technically, calculated in an undisclosed manner.
Availability: ActionScript 1.0; Flash Player 5 - In Flash Player 4, the methods and properties of the Math class are emulated using approximations and might not be as accurate as the non-emulated math functions that Flash Player 5 supports.
Returns
Number - A number.
-------------------------------------------------------
Example
The following example outputs 100 random integers between 4 and 11 (inclusively):
function randRange(min:Number, max:Number):Number {
var randomNum:Number = Math.floor(Math.random() * (max - min + 1)) + min;
return randomNum;
}
for (var i = 0; i < 100; i++) {
var n:Number = randRange(4, 11)
trace(n);
}
-------------------------------------------------------
Now anyone here would look at that and know how to use the function.
Torque Owner Derry Bryson
Default Studio Name