Why WAS Torque3D documentation so poor?

#141 @Matt - nice, I was looking for that. I take it, nothing has changed since TGE 1.4 ?

#142 @Michael P.
Please remember also if possible to collect in the official docs some of the optimal info that Tom and Rene has given us in the forum... sometime is a pain to search in my browser bigbig favourite list to reach them... I think for example the optimal info about SFX system Rene posted some times ago... or a lot of info about materials that many people posted but that really needs to be polished and putted organized in the official docs...

#143 Hey Rene, that is looking cool!

#144 Hey again,

I'm glad that this thread still retains some common sense and hasn't descended into a flame war!

I'm with Giorgio in that there's a lot of stuff hidden away in the forums that could be included in the documentation (if possible). One thing that surprised me was the old "getting started" info on how to integrate Visual Studio, and compile the engine source is missing from the T3D docs. Yeah, its pretty much the same as TGEA, but it could do with being included.

To re-iterate what I was talking about earlier, I think there's a big difference between API docs & user manuals (for the design editors etc.) and actual training materials that show you how to implement functionality X or Y step by step, which the impression I get is what a lot of people (particular newbies or novice programmers) are looking for.

I'm not sure that it's the responsibility of Torque Powered alone to be producing materials beyond the scope of the API and tech manuals (which is why we have the community forums etc.). User collaboration is definitely the way forward, but its important that we don't neglect the absolute beginners by getting too bogged down with programming programming programming.

Perhaps the addition of an academic area aimed at sharing best teaching practises or materials could be useful ?


Rich H.

#145 Great feedback everyone! Thanks.

#146 @Richard: I agree. I think the job of GarageGames would be to make very small simple tutorials, not long drawn out ones on how to do everything, aside from API and showing how the tools work. In my personal opinion full length tutorials on how to script using TorqueScript and simple "how to make a game" tutorials are the community's responsibility. I think they need the tools such as API reference though to start the coding tutorals.

Really it comes down to this:

API and Engine/Tools functionality - GarageGames' responsibility

Newbie tutorials on how to make a (insert game type here) and Learning how to script with TS - The Community's responsibility

Such tutorials are handy to start off with, but essentially I think the best tutorial is a tutorial that says "You can't really make a GOOD game using a tutorial", and the best tutorials should just teach you what you need to start making games and tell you that it's up to API more than just "I need to make a gun" and the like. It should teach you to look toward your engine functions and not templates.

#147 @Glen: My thoughts exactly. There is perhaps one exception... If Torque Powered were to offer professional training (paid of course).

Other than that, I'd like to see a coordinated effort by the community to produce material (not that I'm saying it doesnt already happen! Lots of good stuff comes through every day).

Perhaps its more to do with the way its all collated and made accessible to users ?

#148 I couldnt agree with you more Glen, in fact I always thought it would be a great way to make some cash by offering torque training seminars/webinars/dvds much in the same way that eat3d.com does for UDK, and the typical modeling and animation softwares out there, an individual could probably completely fund his own development selling tutorial video's on doing everything from simple make a working vehicle to more advanced topics like networking a multiplayer game and such. Or even video series going through the steps to make different genre games. Really as a developer all we need is the tool user manual (kind of already started) and the API, anything more then that is just fluff.

#149 Why not make a "sub-site" for tutorials?

I don't mean like TDN, just a tutorial site. I'm sure with their webspace GG could hold it.

The only thing is I think we need some free tutorials, just simple ones, made by the community of course. I still need to learn the API and coding with TS myself so obviously I can't help yet. ;)

#150 Not sure if anyone mentioned it,I cant figure out how many engine related global variables available in Torque, for example $Game::argc, $Game::argv,$isDedicated etc. It would be nice to have a list.

#151 @Sei - I would have a hard time imagining them not including all of the global variables. These are essential to API documentation, especially for those without the source.

#152 @Sei - We've taken that into consideration. Global variables will be accounted for.

We've made a lot of progress in automating our auto-documentation process. We are still driving hard on Doxygen, Due to it's tagging system and what the developers have accomplished, the CHM file will now actually resemble a true TorqueScript manual covering overview, syntax, global functions, class methods, class members, and callbacks. I can't tell you how excited I am to see the team putting this much effort behind the task.

#153

Quote:the CHM file will now actually resemble a true TorqueScript manual covering overview, syntax, global functions, class methods, class members, and callbacks.

And examples? Like what Glen was expressing in his comment #133...
I liked what I saw, including the little example, in that naturaldocs test doc you posted a link for. I hope the Doxygen version is as good as that in terms of the presentation and content.

#154 I agree, I really like Natural Docs' very elegant out-of-the-box presentation too. We'll be trying out both ND and Doxygen for output when we have our final data available and can easily see what is giving us better results.

Examples will be contained in the reference documentation.

@Novack
Thanks :)

#155 Good to see this effort, you are slowly making it so people have less things to complain about, think about the forums before you do that :-).

#156 Thanks Rene. Sounds good.

#157 Well I like the layout of what Mich posted, but I just think that two things need to be done:

1: This one I consider rather important. I think that sub topics should be shown on the side rather than when clicking on functions it shows a list of all functions, they should be broken up into categories. so Functions would open to show each function split up. For an example look below suggestion two.

2: The second one doesn't have to be done exactly like this, but I do think things should be split a lot. This isn't completely needed, but it could cut down on confusion. This is kinda a plus on the first suggestion. Each script reference should kinda be a sub topic on the side. Instead of having one link to the full reference, or all the vector references and stuff It should be split up in categories like so:

Script Reference
-Script layout (containing variable definitions, functions, etc. More or less the "full reference" tab that is currently on the T3D docs)
--Variables and Arrays
--Functions
--Loops
--etc
-Predefined Functions
--Vectors
---Vector Addition
---Vector Subtraction
---Vector Multiply
--Ray Casting
-----------------------etc

with things like vector functions having all the add, sub, mul etc. And Ray casting having only the ray casting functions, and the like. I think the calculations should be split up and as small as possible. That way it minimizes confusion. That would take extra work, so the other way of doing it would be to just put all the vector calculations in one page and stuff like that to make it a bit easier to finish the docs.

#158 One thing that would be *really* useful, is some kind of remark or separate section with links to the new things on torquescript since T3D.

Rene has been reporting some really cool stuff, but having the improvements emphasized in the docs, would be cool.

#159
@Novack
Consider it done.

#160 Sweet. Ok, so you guys hurry along and do those docs!

Just kidding of course ;)

But hey, If you guys work with some of the docs and get some good stuff can we get some early looks at it?

I'm hoping things go smoothly because I'm really looking forward to 1.1.

Offtopic: Are you guys gonna be fixing those random crashes with the new version?