Why WAS Torque3D documentation so poor?

#21 ?

#22

Quote:The difference is price. I paid $150 back in TGE times for full engine code and I never expected it to be easy to figure out. If I were just showing up and putting down $1000, I guess I'd expect a lot of quick-start tutorials too, not to mention comprehensive demo scripts, levels, API refs, etc.

That's really where I was coming from. If you plan to sell a product as such a price (in the face of less costly and even free competition, no less) then you need to make sure that the customer can not only have access to a sweet set of features, but to also make sure that as many customers as possible have access to a repository of information that allows them to effectively utilize the product.

This whole experience has been like a computer-illiterate Windows-user trying to install a barebones version of Linux with no help or instructions. Sure, they can fumble their way through it, but it ain't easy or pleasant.

#23 @BT: the debate about TDN has been long and hard. Im among those who believe that it accomplished so many goals, while the problems it suffered were due to lack of maintenance and control, and the misunderstanding og the goals of the wiki.

#24 RE: TDN: I remember hearing that term a lot, but I never knew exactly what it was, let alone that it was a user-editable wiki (granted I wasn't really looking for docs at the time). Not sure if this is a case of bad idea of poor promotion of the thing once it existed. Or was it a devs-only wiki? Because that never works out.

Here's an example of what I was thinking of:
wiki.garrysmod.com/?title=Serverside_Lua#Player_2
That's a function and callback index for Player objects in "Garry's Mod," which is a Source engine script extension some kid wrote several years ago. The value of what people have entered as details and examples for each item varies from good to terrible as I recall, but simply having the list itself was very helpful back when I tried to use it.

@Novak: I see your point... a lot of the utility functions are completely hidden unless you know where to look. I spent a good chunk of time long, long ago writing code to convert world space to object space only to learn this is a standard engine feature.

#25 @Novack: Depends on the detail of the API. They could just use a better commenting system and then extract that and use that for a very detailed documentation presentation as well (have seen some of that beginning to happen in a few places as well). That being said don't get me wrong, I support a lot more documentation as I feel is lagging behind everything else (with the exception of a good demo and hopefully that will be resolved by 1.1 release).

I know they tried the community approach earlier and I guess that didn't work all that well, but I am sure if they offered up some kind of incentives they could probably get a lot of the work done for next to nothing.

#26 On top of API docs, more mini-tutorials on features seen in most games would be great. Perhaps some simple AI tutorials, new tutorials on the art pipeline, optimizing, inventory systems, database integration, etc. Granted, I haven't looked at the docs in a month, but I didn't see much then.

Thanks for the open-minded replies GG. :)

#27 I had thought that someone was specifically assigned by GG to do only documentation. If so, they are doing a lousy job. If not, they should hire someone to do so.

#28 I don't think they're doing a lousy job at all. I think they're approaching documentation in an inefficient manner, by documenting after the fact. Docs should be written as the product goes through its design and development phases, and then revised to reflect the final product. To have one person come in and be the documentation person is just unworkable, especially with something on the scale of T3D (or any of their engines for that matter).

#29 I think it's more down to a sense of direction. Things have been so up in the air at late at GG/TP, but now we are starting to see structure and direction from the blogs that Eric has been posting, once the engines bugs have been fixed at 1.1, and a stable release is out the door, more documentation will no doubt follow and hopefully no further additions or features will be added to the engine (just patches) until we see a major set of documentation with everyone working on this area only. It would make the engine solid and give it the TLC it deserves, as there is no point in having a good engine without the rest of the car to show it off in. I just hope that there are enough resources available short-term to cover all of the engines as I know what saturation point is - and it's not good. I must admit, our project is strugling a bit due to the lack of docs and lingering bugs from earlier releases not being fixed, and as we're reliant on people that have historical experience to be able to port code over. Hope the next BETA is a bit more bug free.

#30 yup, binary users at this point are left on the dark.

this does not surprise me tho, I have been following torque for some time now, a few years, and as far as I know, there is always been this lack of documentation or poor references about torque documentation.

lets be honest, look other game devs forums, and this is not from a year ago, this is from years back and still going. pretty much all complains are from this same issue.


Maybe is time for Torque to start doing something real about it, and not let it slide as it has been for years, they have to listen to members needs.


looking forward for some good documentation, hope it is done soon. cross my fingers.

engine is good, great software, awesome implementations, great people
Now, shows us how to make good use of it.

#31

Quote:I don't think they're doing a lousy job at all. I think they're approaching documentation in an inefficient manner, by documenting after the fact. Docs should be written as the product goes through its design and development phases, and then revised to reflect the final product. To have one person come in and be the documentation person is just unworkable, especially with something on the scale of T3D (or any of their engines for that matter).

While lousy may have been a little on the strong side, it has been anything but good. There are several areas that could/SHOULD have been documented already. Most of the TorqueScript documentation should have been done.

I can understand why we don't have documentation for some of the new features, but things that have been in Torque since 1.4.x should have been documented already.

#32 @Michael, now might be a good time for that blog you promised for last month:

Quote:Now that 1.1 Beta is out, I will be posting a blog about Torque 3D documentation next week to discuss major changes to the content, reference, and structure...

www.torquepowered.com/community/forums/viewthread/104311/7#comment-724635

Some of us perhaps are starting to feel starved for information...


Please sir...

#33 I have to agree with others here as far as the documentation leaving alot to be desired. I have a day job as a lead software engineer, as I have for the past 15 years. I don't do anything related to game development. I basically became interested in the game development side of things about 5 years ago, but I don't have ambitions of entering into that market (this is a hobby only). I can say this. About 4 years ago I was led to believe that the this engine was something that it's not. So I gave up. Recently I became interested again, and I decided to purchase the binary of T3D after looking at the nice video tutorials because I thought to myself "wow, maybe they are trying after all these years". Funny thing happened though.... the documentation is still lacking. Yeah, it's gotten better, but BAM here's a post in the private forums about the same old thing.

Even if I wanted to use this program at work to demontrate 3-dimentional airspace activities related to air traffic control, there's no way I could prototype it in a reasonable amount of time. Why, the documentation? Just today I asked how to connect to a database from T3D. I can't find a professional, well thought out example of connecting to a database, retrieving data, and pulling it into the engine. Let just say I wanted to show 3-dimenionally a bunch of aircraft using latitude, longitude and altitude, where the data is stored in a huge relational database. Where do I find that? I bet not a single person here can point me to an example.

Sad really. I bet there are block buster applications out there, gaming and others, that will never happen using this product simply becuase the documentation is, well, horrible.

#34 @Frank: Very well stated, and an excellent point on the use of the engine for more than just games. It's becoming more and more commonplace to see game developers in areas related to aviation and simulation, and there's no reason an engine meant for games can't be used to simulate a real-world application, especially one that uses PhysX, like T3D.

Except for the lack of documentation and the lack of useful support.

All we have to rely on are occasional posts from GG staff and the people who have already managed to hack through the code before us to solve a similar problem. However the issue is that while the process may work, is it the most efficient? We don't know because the creators have failed to show us how the engine works.

#35 In terms of full-blown examples? I don't think its up to GG to provide that. They offer a game engine. You have source access so the possibilities of use are almost endless, so how on earth can they cater for that level of support?

API documentation, absolutely. Examples about how to hook up a database? No chance.

#36

Quote:API documentation, absolutely. Examples about how to hook up a database? No chance.

Agreed. Let's just get to the minimum first. I think that once you have more proficient people around here, the other stuff will become a lot easier.

#37 I think really what is asked for is what each process does, so that if you throw something in there blindfolded you're not gonna break it. The trouble is, you have the foundations (the graphical element) but when you start delving into the code aspect you really need to know where you need to make the addition or change. It's the not knowing that is the frustrating part. Things are sure a whole lot different than the TGE days, even the books are now out of date - but Torque script remains the same correct?

#38

>>Associate Phillip O'Shea
>>#35
>>03/04/2010 (3:40 pm)
>>In terms of full-blown examples? I don't think its up to GG to >>provide that. They offer a game engine. You have source access so the >>possibilities of use are almost endless, so how on earth can they >>cater for that level of support?
>>API documentation, absolutely. Examples about how to hook up a >>database? No chance.

Why no chance? Sigh.

At a minimum an API. But guys, that's not my point really. We're going on years here and it's the same old complaint (inside and outside these forums). The proper documentation just isn't there.

What should I have expected for $100? And now they want $1000 for poorly documented source code (very well written though). I think it's backwards, give the engine away for free and charge $1000 for comprehensive documentation.

While I'm on a rant, if I want to purchase assets that are shown in the shop. Which ones work with which versions of the engines? Some of those assets are so old, that they predate TGEA. Do they work with T3D? Again, another example of the confusion here. GG shows requirements for the assets, but not an engine requirement (i.e. v1.0.1 and above, not compatible with TGEA 1.x and earlier).

#39 I think that GarageGames just didn't have a clue for so long on how to run a successful business. I'm hoping that with new management, these issues will be addressed. I feel pretty confident with the amount of money that has been pumped into Torque, they can't afford to fail. I think this is why Unity3D gained a massive amount of the market share. I would dare say that Unity3D eclipses Torque in active users.

If I hadn't already purchased Torque, I would be using Unity Professional. Don't get me wrong, I think Torque is the more capable engine, but as far as documentation and resources go, Unity wins hands down. If they don't deliver quality documentation soon, they will fail.

#40 Expectations are personal and differ greatly. All GG can do is provide documentation that addresses the broad sweeping concerns of their target audience. They cannot do this while addressing the concerns of an individual.

Unfortunately, Frank, you're just one of a handful of people who need database support. You should seek out those other developers before crying foul on GG for not supporting you on this. But then again, these are my opinions, based on my expectations from GG. Yours differ, I get that.

Quote:I think that GarageGames just didn't have a clue for so long on how to run a successful business. I'm hoping that with new management, these issues will be addressed.

You've been here a few years longer than I have, so I'm sure that you have insight which I cannot understand, but from what I see they are really trying to do exactly that.