Why WAS Torque3D documentation so poor?

#221 @Sei - When TGB went through QA we fixed a number of documentation bugs. The same will happen for our other products.

@Jon - It's hard to do everything at once. As you know, we are converging code and product lines at every reasonable opportunity this year. That will help reduce the amount of code coverage we have per person. No one here wants to push back anything but we couldn't maintain the same level of participation and fix TGB, update TorqueX 2D/3D, and ship iTorque 2D 1.4.

@Giuseppe - Agreed with the first part. We started contracts with several longstanding associates. That will help. We are also building time into current schedules so that our core developers are writing docs. That's the real mid/long term solution. As for the QA dept, they will never find every bug. Especially in the near term. But over time we will have more and more automation in place which will greatly reduce the number of bugs that show up in the community after a release. The QA lab is run by a senior developer who spent many years at EA. I have a lot of trust in him.

#222 Eric,

I didn't want to express lack of trust, if that was the result of my post I do apologize. Let me elaborate.

I've expressed a worry because QA is a task that's supposed to be lead and carried out by product experts. The strongest UDK expert will be simply unable to perform a real quality test on T3D just like the best T3D developer in the world will be lost at his first approach to UDK.

I do believe that in time they will acquire the needed competencies to perform real QA tasks on Torque products exactly because they are competent people, and here's my worry about the present QA tasks. The first 6 months will be invested more in acquiring the necessary competences than finding quality issues: this is just an unavoidable part of the process, thus it worries me to read about all the current expectations from the QA line posted here and in other threads.

I'm confident that in due time the QA line will be a great asset but at the moment I'm receiving from GG too many expectation messages about this process.

#223 @Pino

That's exactly why I was brought on as QA Lead. To be the on site expert that knows the tech to write the needed test cases. I've been working with Torque Technology for the past 7 years.

#224 @Pino - I see what you are saying. If the community expectation is one of a perfect solution overnight, then yes, we've oversold it. Several times on several threads I've tried to express that it will evolve over time. It's not a magic bullet. But we do have qualified people that understand the challenges and the tech.

And Scott it right, we put him on site at the lab to increase the ramp up time it will take to have a well oiled machine.

No offense taken in your post at all. You are a valuable resource to our community and your perspectives are valuable.

#225 @All - Good news on the documentation front. We have recently picked up three contractors to help me with the work. Since our last update, we have gotten more work done and with the new help we should make steady progress.

#226 @Mich: That's good news.

@Eric & Mich: I'm rather confident that things WILL be done, but it's always a question of WHEN, and I don't mean that just on the T3D side of things. Good example: We wanted to release our game Kino One at around spring time last year. It was released December 10th.

@All: I'm sure that things will work out, although I do understand it from the position of the people who are trying to make games right now. In my honest opinion 1.0 was released too early, at least for the binary side. There probably are quite a few people coming in and wanting to make a game right now off the tech, but are unable to due to lack of API. Both sides are understandable, but what I get from it is this:

1. The fixes will be released, however, there probably won't be any release date posted until it's almost done.

2. The community will probably continue to get worried and ask about what will be in the new release, it's inevitable when people get restless

I just think it takes patience on both sides, but then again this is just my opinion.

Good work guys and keep going.

#227 I did not invest in Torque so that I could exercise my patience.

Nothing is more frustrating then running into some obscure showstopping bug, seeking help from the forums to be told it will be fixed 'SOON', and 'SOON' is always "Any day now...".

My observed opinion about GarageGames is they can get allot of mediocre Game Engine in the market, but never seem to accomplish having ONE great Engine. GarageGames exceeds very well at building hype and talking about what they are doing/going to do... But most times all i see is allot of blowing smoke, weeks and weeks and weeks later....

#228 All, if possible, please stay on topic of the documentation. That would be much appreciated by myself and the other writers.

#229 @Caylo - I'd be glad to answer specific questions for you if you could point me to what is frustrating you. If the statement is in regards to the documentation, have you looked at the earlier post where we dropped a link to the current unreleased version?

I agree that we have a lot of people spread out over a lot of engines. That's why convergence is such a big topic for us this year. It's the only way we can solve that problem. Otherwise we just spend too much for an incremental increase in quality.

#230 Sorry Michael; I always thought the supplemental Torque Doc's were fine, just not very highly technical. What is missing along the lines of documentation is well commented CODE. Have you seen some of the other Game Engines? Some of them have wonderfully detailed comments IN the code itself- no reverse engineering just to figure out what the programmer was thinking at the time.

Eric; Whats frustrating is i always seem to be waiting for the next patch/upgrade to fix all the little bugs that are known and said to be fixed for that next build. Perhaps some 'Bugs and Fixes' forum or some type of evolving code-drop. Just having a more active participation in the forums as Engine support and bug fixing would be exponentially helpful.

#231 @Caylo - I've been in your shoes before. I was a community member long before working here and finding fixes in a forum that weren't in a release was one of my biggest gripes (especially when they were years old). One of Scott's jobs is to lead the effort of validating forum bugs and enter them into Jira where they can be fixed. We've not had a developer working in QA in the past so having a bona fide C++ Torque developer doing this work is a huge benefit.

Many bugs in the forums need to be validated and detailed since sometimes community members shouldn't be expected to write our bug submissions.

When you come across a bug that you noticed isn't fixed, feel free to send an e-mail to Scott with the link. He will have someone validate the bug and detail the bug so that it's in our work flow. Scott and his team have been doing this for TGB 1.7.5 and iTorque 1.4 and it's working well.

Scott, can you post directions in this thread on how you want people to contact you?

@Pino, it's actually a reasonable answer to your question as well. Our community does have deep knowledge on our products. We just haven't had a good system in place for harnessing, confirming, and vetting the fixes.

#232 @Mich: Sorry, one of the points I was also meaning to stress on my opinion that 1.0 was released too early was the documentation. I also meant bug-side but documentation enters into that whole "it was too early for binary".

I have to agree with some of the troubles of buying the engine and not having adequate documentation for the binary side of things. I have to agree with that frustration, and if I were not focusing on something else waiting for said documentation I would be rather upset too. I guess I'm lucky to have website work to do :P

#233 @Eric: I guess you do know that I'm a strong supporter of community bug fixing work :) I do understand that there is excitement about the newly introduced structure so expectation can be driven by that while posting around.

I'm strongly positive that you're doing a very good job lately. As I wrote in the blog, Torque engines are very well designed from my professional point of view. There are things that should have been corrected long time ago but a lack of organization doesn't make bad the engines, it just makes bad the business which I hope now will be revitalized by this new structure.

Now we are definitely off topic :)

#234 I'll start up a new thread later for the new bug submissions processes, or perhaps a blog, maybe both. In the mean time let's get this topic back on track. My apologies to Mich for us derailing his thread so badly. I'll make it up to him by using an image I had him make 2 years ago and never had an opportunity to use.

#235 @ Scott: Actually it's Jon D's thread ;)

@Torque Staff: Perhaps regular (weekly) updates would calm the masses. No ETA's necessary, but certainly welcome.

#236 Why do the official docs have PhysX docs when PhysX is not officially supported ? ..quite confusing position IMO.

(BTW, ever try to follow those PhysX docs ? ..your exports will fail unless you know more than the docs tell you. Not to mention the way opencollada DAE files are handled during T3D import will cause your physx work to fail nearly all of the time.)

..sooooooo why are those docs in the official docs ?
Tell'us the story plz, I'll grab the popcorn!

#237

Quote:I'll start up a new thread later for the new bug submissions processes, or perhaps a blog, maybe both. In the mean time let's get this topic back on track. My apologies to Mich for us derailing his thread so badly. I'll make it up to him by using an image I had him make 2 years ago and never had an opportunity to use.

@Scott - If you're intending to revamp why not go a bit further and use a ticketing system or an easier to implent directory structure that seperates "fixed" bugs from the ones in progress. I'd be suprised if you don't already have an internal ticketing system in place that you could expose to the web with a minimum of changes.

If you go with a forums method then perhaps call the other "Completed" because some of the reported "Bugs" could be there because of some limitation or some thing on the order of an obscure niche annoyance that would take an absurd amount of time to fix.

#238 @Jacob - I'll go ahead and make one last post about bug reporting and QA:

Quote:...why not go a bit further and use a ticketing system or an easier to implement directory structure that separates "fixed"...

Scot has done just that. We use Jira for bug tracking, and Scott has worked with me to develop a forum system for community bug reporting and tracking. Example:

- iTorque 2D 1.4 Bug Forum

- Bug Report Standard

- Sample Bug

- Results of a release

As you can see, Scott has everything under control. Now, back to the documentation discussion. I'll have an update to post later today.

#239 @Michael - Awesome, I look forward to it being used with T3D. :)

#240 @eb -

Quote:Why do the official docs have PhysX docs when PhysX is not officially supported ?

Very simple answer to this. We introduced PhysX support. People wanted to know how to use it. We documented the parts specific to Torque 3D, which I felt belonged in the official docs. For robust PhysX API documentation, users are expected to read their docs. For what we implement, users expect that to be documented.

Quote:BTW, ever try to follow those PhysX docs ? ..your exports will fail unless you know more than the docs tell you.

Honest answer? No, not outside just reading them. I am not an artist. Without getting an artist to help me, I couldn't even tell you how to create a cube and export from 3DS Max. Sickhead created the PhysX implementation, so it made sense to let Russel write the PhysX artist docs. Since the initial release, I have not checked in with Russel to see if the tutorials work with the latest exporters and PhysX. However, I have faith in what Russel wrote, since the implementation came from his team and they are using it in their Pacific demo.

What I should have, and will do, is install the necessary software (3DS Max and PhysX) and try to walk through the tutorials other people write. While we cannot control PhysX or 3DS exporters, I will make a better effort to check for compliance and completion.