Why WAS Torque3D documentation so poor?

#161

Quote:Ok, so you guys hurry along and do those docs!

Believe me, we're crunching :) This is pretty much a complete pass on the codebase and the codebase is quite large. We're also using the opportunity to bring the entire console function stuff over to a new system that allows us to do some cool stuff in the future.

Quote:can we get some early looks at it?

You bet. Would not make sense to just put something out without shoving it through a feedback loop first.

#162

Quote: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.

I didn't respond to this earlier, but thanks for the props. That engine documentation was great in terms of learning engine functions. It was really helpful, and I would like to see something similar in T3D's docs, but the thing is that could also mean that the new version wouldn't be released for quite a few months. Either way I'm looking for the new version and I'd love to make a game, but I gotta wait anyway (not cuz of torque, but because of websites and another job).

Quote:Believe me, we're crunching :) This is pretty much a complete pass on the codebase and the codebase is quite large. We're also using the opportunity to bring the entire console function stuff over to a new system that allows us to do some cool stuff in the future.

Yep, I was kidding around, but on the serious side I know how that is. I've been a part of the release of two games with over 4 years work total (granted that isn't a long time working on games, but still). I do know how it is to say "we're gonna try to get it out in spring" and it's released in winter, Kino One was that way for us...

Either way I hope you guys pull off some great stuff.

Quote:You bet. Would not make sense to just put something out without shoving it through a feedback loop first.

Good, I wanna be one of the ones lookin' at those docs. ;)

@all GG team: Guys, I want that new version BUT...big BUT...Please don't rush it out. The community would love to see the new version, but it's better to release a stable version than another beta that requires a 1.11 release to fix a lot of the issues. I wanna see it bad, but I'd rather see a version that is rather stable.

#163

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

did you say callbacks? I thought i heard the sound of music to my ears.=)

hmm... a full script reference including callbacks, script documentation including mission loading and torquescript changes, and then a promotional discount; geez what am I supposed to complain about now?

I'll find something. until then, very nice progress I'm seeing here.

#164

Quote:I hope the Doxygen version is as good as that in terms of the presentation and content.

This was a concern of mine as well. I immediately sided with NaturalDocs due to its HTML format. It's very similar to how our internal doc system is set up, and I felt like I would have a lot more control over ND presentation over Doxygen. Tom took the time to walk me through some of Doxygen's intricacies over the phone, which was a big help.

It turns out that I have just as much control over Doxygen formatting, so the CHM is looking very nice. I can even use the same CSS settings from our online docs in Doxygen, though I may be tweaking both for a cleaner presentation.

All in all, the content will be the same no matter what. We have a clear concept of what needs to be documented and the verbosity of it.

Here is a brief breakdown of what happened this past week:

* Organized the team
* Collaborated on doc tech
* Fixed our auto-documentation process (Rene and Tom have been writing new code in the engine to support more flexible and robust docs)
* Prepping a commenting standard
* Readied the auto-doc environment
* Tested the updated Doxygen system

We spent this much time on the prep and tech because we are not looking for short term wins. We want long term solutions, both for our effort to document the engine better and for the end user writing their own comments/docs.

The best part is that everyone on the team is excited and very happy this is finally happening. Years of neglect on reference docs built up beyond what 1 person could feasibly fix in a reasonable amount of time. Having the entire Torque 3D team, contractors, and some Torque 2D team members work on this is awesome.

#165
Ok, just some teasing.



We're making good progress. Quite a bit of engine-side dev, though. But we have some cool new stuff.

I'm off to bed.

#166 Now that is nice.

#167 yea that does look nice.

it'll be interesting to see how comprehensive Torquescript->Language Reference->Objects and Classes will be. this is probably where new torque users experienced in programming will be looking first.

#168 Ok, Yea...That looks good, and actually It's similar to what I was wanting too. I take it you guys are using other documentation as a reference?

Wow....really...Give us a demo soon plox! PLOX PLOX PLOX!!!

Good job guys, hoping to see more soon, and it's really nice to know that everyone is pitching in. Wow this might only take a month or two.

PS: When the next beta releases can us non-pro people have the sample docs...pleeeeeease? ;)

#169

Quote:I take it you guys are using other documentation as a reference?

Sort of. CHM has always been a favored format for technical documentation. Havok's CHM docs are a big influence, and we also apply our own means of organization. So it's a nice mix.

Quote:When the next beta releases can us non-pro people have the sample docs...

Absolutely. This is going out to the public before another Beta, no waiting for an engine release.

#170

Quote:Sort of. CHM has always been a favored format for technial documentation. Havok's CHM docs are a big influence, and we also apply our own means of organization. So it's a nice mix.

Cool, I also prefer CHM or pdf to a browser file like html. I just have this thing about either reading it on paper or in a help file...I don't like reading manuals from a browser...Doesn't make sense but that's how I do things.

Quote:Absolutely. This is going out to the public before another Beta, no waiting for an engine release.

Great. I'm hoping it's the same with any docs released with betas. I think it is already that way if I am correct, at least with the online docs.

Side Question: Is there any chance of us non-source people getting previous versions like TGEA or previous releases of T3D? For instance, when 1.1 comes out could we still download 1.01?

Another Side Question: Any chance of getting a full change log? I would like to see things like "fixed tiling terrain" and "fixed fog for T3D" there. If it is possible, can you guys give us any small list at the moment?

#171 Well, CHM readers embed your operating system's browser, so why should it matter? ;)

#172 I think It might be the top interface or something...I dunno...maybe something else. I can't really make full sense of it. Maybe it's the fact that in a CHM help file you only have searching options and such. It just has a better UI I guess :P

If I don't make sense just laugh it off and don't worry about it. lol?

#173 Small update: I've been working on the organization of the CHM, since it has become a full on TorqueScript manual. We want to make sure it's easy for someone to just jump straight to what they want to read about:

#174 Ok, Mich...sorry guy but we're gonna have to take you out back and have you shot....no choice...

It looks great! So when do we get a download? (lol)

#175 @Glen - Haha. Is that an Old Yeller or horse reference? =)

Quote:So when do we get a download?

I don't want to hang myself. I can tell you that all our technical changes are in place. Full on content creation mode starts tomorrow, which means nearly every Torque team member will be writing docs and comments. I'll spend each day and the majority of my weekend reviewing everything.

#176 Good move (at least) and good luck for the mass of work that awaits you…

#177

Quote:Haha. Is that an Old Yeller or horse reference? =)

Naw, more like...executioner style...but hey, If you DON'T do an awesome manual you don't have to worry about it ;)

Quote:I don't want to hang myself. I can tell you that all our technical changes are in place. Full on content creation mode starts tomorrow, which means nearly every Torque team member will be writing docs and comments. I'll spend each day and the majority of my weekend reviewing everything.

.......
Refer to my previous post.

Wow...so is the fog fixed? and the terrain tiling? and the (insert issue here)?

So what you're saying is that the ENGINE is ready?

#178 Glen, I think Mich is talking about the technical changes concerning the engine documentation, in other words, what they have been talking in their lasts posts.

#179 Ahhh...Either way...my last post stands.

#180 We are now in full doc mode, folks. People are getting assignments and documenting as we speak.

@Glen - My sole attention and the team's efforts are focused on documenting the engine right now, so I can't speak about bug fixes. We have other threads going for that, though.