Why WAS Torque3D documentation so poor?

#1 We definitely think a lot more effort should be put into documentation for our engines, especially ones we claim as our flagship. We are soon going to implement measures that will cause the engine team to contribute to engine documentation. Additionally, we have been discussing plans to increase our writing staff.

To the point, the documentation is not good enough and we have someone in charge pushing to allocate more resources to make it better.

#2 Good to hear Michael. Hopefully this documentation will come sooner than later.

Tutorials would be great, but I really think that we need thorough API documentation from both the C++ side and the TorqueScript side.

#3

Quote:I really think that we need thorough API documentation from both the C++ side and the TorqueScript side.

Totally agreed with you there. That's what I was referring to with the engine team contributing. Do not think it's quite a forced decision, though. The developers agree it's time we put the full force of everyone on the team behind documenting every ConsoleFunction, ConsoleMethod, usage string, and as much Doxygen as we can in a given time frame.

I have much higher hopes for 1.1 documentation with these plans in mind.

#4 Great, looking forward to it. I know that I have been pretty negative in the past, but I honestly think that with the growth of Torque and Unity, those are the future. A lot of my negativity about Torque has come out of frustration. Torque has never been real great on documentation and tutorials. This should help out a lot.

#5 Your honesty is appreciated. There is frustration on both sides, so I understand. We know if you guys weren't trying to help, you would not be posting here. You'd be gone already. As always, thanks for the patience and the support.

#6 A lot of us have invested a lot of money into Torque Products and we would like to see you succeed.

#7

Quote:
We are soon going to implement measures that will cause the engine team to contribute to engine documentation. Additionally, we have been discussing plans to increase our writing staff.

Michael you still neglected to answer the question.

Tengu's question asks why the documentation is so poor, and honestly it's a good question which no one at GG is capable or willing to answer.

people may want documentation, but people just really NEED an api reference of global functions, object fields, methods, and callbacks. developers can figure out what functions and methods do by their names and parameters so detailed documentation is NOT necessary just provide us an updated list!

Once a basic list has been provided, then you guys can go back to your discussions about improving documentation.

#8

Quote:people just really NEED an api reference of global functions, object fields, methods, and callbacks.

Agreed, just as I said to Black Tengu. That's what I was referring to with the engine documentation:

Global Functions = ConsoleFunctions

Object Fields = Usage strings

Methods = ConsoleMethods

Callbacks = Doxygen comments

When those are filled out, we will be able to generate robust CHM files and convert those into lists (if necessary). Most, if not all, of the list exists already in the Console dump and Script Reference CHM. Unfortunately, a large portion do not contain useful descriptions.

#9 Any ETA on documentation then? Are we looking at documentation a month from now or are we talking a year from now? To me, documentation would be close to priority one, perhaps right behind stability.

#10 At the last meeting, we decided that the new engine (read, API) documentation should go out with the 1.1 final release. This will happen after GDC. I believe the engine will go through one more beta, then release. I don't have an exact time line to give out, though.

#11 I agree with all Tengu and Sean have stated. My situation is a bit different in that I have already been forced to purchase the software (I'm a student of game design and it was a requirement for the course, and we were unable to purchase any sort of Student Edition, we had to purchase the full engine). Now, having already paid for this not-entirely-inexpensive engine, I'm stuck with very, very little reference material with which to build our game. It's extremely frustrating for me, knowing that I've lost a large chunk of money on this engine.
We have a team of five currently creating a turn-based strategy game, and we're stumbling through it as best we can. However, because of the lack of documentation, tutorials, books, manuals or any other real reference material, our production has been extremely slow, and some parts of the game have been cut out entirely because we just don't have the guidance necessary.
For a thousand dollars, GG really should have put more thought into making sure the customers can actually use the software effectively, rather than build the engine, take a few awesome screenshots, then broadcast, "Look what you can do with this engine!"
I can say with certainty that the students here that are being forced to buy the engine have a great opportunity to utilize a nice engine packed full of features after graduation for their indie projects, however will not utilize it simply because the developers failed to package a manual with the product. That's a pretty large chunk of people buying your software and not doing anything with it, when they could be out there working on small indie projects that would, at the very least, increase Torque 3D's presence in the community.

I stated all of that in the hope that it will help shed some more light on the opinions already presented, and the impact the lack of docs is having. I hope GG will prioritize this over everything save critical issues.

Thanks for reading.

#12 @Tom - Both Sean and I have purchased the engine already. This is the private forum. ;) Let me just say, I understand your pain. Very frustrating. It appears that GG has yet to learn from past documentation issues/problems.

#13 Seems to be a programmer's mentality and get answers on the forum that really kind of obscures the documentation at some points. Typically if I want to figure out how some console function works, I search for it in the project file and then look at the code. While that isn't an option for everyone (and in particular those without the source), it typically is what happens instead of me trying to consult some documentation on all the different console options there are.

I guess that also goes into the approach they need to figure out with their documentation. Do they want to write an extensive API document that is well extensive and requires a lot of updating every time something is touched, or do they want to focus on the tool set and have a much more detailed approach toward getting documentation out for that along with some of the most commonly used scripting functions.

#14 Yeah, I have to say that, while I totally support that users deserve more docs at this pricepoint, it's easy to understand why it gets pushed to the back. A lot of long-time users who think like I do would rather see amazing new functionality than a comprehensive set of docs, because we're used to how the engine is put together and we're also accustomed to using code searching and forums/etc to figure things out. We've spent years with this codebase and so dev time spent on an API ref or basic tutorials feels like wasted effort.

Obviously binary-only users can't really do this, and so there really should be a solid API reference for them. I can't imagine what it would have been like trying to build game scripts without being able to go and look at their C++ connections, or even find out what commands were available in the first place.

Documentation on the newest subjects would be very welcome even to the seasoned TGE veteran, I believe. Things like the new rendering system and the physics abstraction layer deserve a bit of how-to. Obviously I'm biased here because these are the parts of the code no one's really had time to dissect yet.

So to be fair, and thinking back to my earliest exposure to TGE.. there are plenty of core concepts that new users have to wade through that could be simplified into comprehensive tutorials (networking concepts, proper use of datablocks, code<->script interface, GUI rendering, and so on). We answer the same questions about these issues in the forums every week, so they might as well be put into a static location.

Anyway, this is long-winded. I definitely support any kind of comment-harvesting documentation system that forces devs to 1) add additional comments to engine code itself and 2) moves API documentation responsibilities towards the people who wrote the code in question.

#15

Quote:A lot of long-time users who think like I do would rather see amazing new functionality than a comprehensive set of docs, because we're used to how the engine is put together and we're also accustomed to using code searching and forums/etc to figure things out. We've spent years with this codebase and so dev time spent on an API ref or basic tutorials feels like wasted effort.

I think that is the same attitude GG must have. Let's be honest, good documentation isn't exactly as sexy a marketing point as something like SSAO, but it is more important.

#16 I'm not sure if it's a marketing thing exactly... at least not for marketing to new users. When T3D first showed up its primary customer base was people who already knew the engine code. I know most of us wouldn't have paid for an upgrade featuring "maybe a few new features and tons of detailed documentation" after we'd taken all that time to learn the code. On the other hand, now that basically all TGE users who could upgrade have and new users are the primary group GG is selling to, I'll reluctantly admit docs should be a top priority for the sake of doing more business and keeping things moving overall.

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.

This is partially off-topic, but have there been any considerations regarding a set of secondary wiki-style docs in addition to the official stuff? Something hosted by GG but mostly maintained by the community (not that dev contributions wouldn't be excellent). I think we can all agree that this community generally enjoys helping people solve their Torque problems, and it would be great to have some central hub to store useful user-generated solutions/tips/tutorials that's less "fleeting" then the forums, not to mention that's moderated to remove the repetitive or otherwise distracting data.

#17 @Joshua, you make it sound like writing and mantaining a complete API documentation is like hell. I think is not.

On one side, we are talking about people that is writing a game engine, so Im pretty sure they can manage to write docs.

On the other, I really dont see the problem in modifying the docs when changes are made to the code. That can even be automated.

The big issue I think, is to make the big step, to actually write the documentation, specially because the engine was not even feature complete until recently, so writing docs on a moving target *can be* wasted time.

Im really use to dive into the portal, looking for info in forums, blogs, tdn and whatnot. Im a member with sometime here, I know how it works. Is it cool to count with the community when the house is in flames? Its the better Torque has. Has that anything to do with documentation? Not really.

#18 And btw, I think there is a misunderstanding here, about what an API documentation means.

It is not only for the purpose of knowing what parameters a certain function needs. Its for knowing a certain function exists. And this is not just for the script API.

It happened to me a couple of times, to be more time efficient to write my own function, than to search into the code for any possible included method. The math unit is a good example.

#19

Quote:This is partially off-topic, but have there been any considerations regarding a set of secondary wiki-style docs in addition to the official stuff? Something hosted by GG but mostly maintained by the community (not that dev contributions wouldn't be excellent). I think we can all agree that this community generally enjoys helping people solve their Torque problems, and it would be great to have some central hub to store useful user-generated solutions/tips/tutorials that's less "fleeting" then the forums, not to mention that's moderated to remove the repetitive or otherwise distracting data.

Isn't this what TDN was? I don't think TDN ever turned out to be all that helpful. Some work was done, but a lot of it got out of date fairly quickly, especially the TGB stuff.

#20 Hehe. Dont touch that unleast you have a good armor mate.