Prev/Next Blog
by date

Plan for Rick Overman

Name:	Rick Overman
Date Posted:	Dec 17, 2003
Rating:	5.0 out of 5
Public:	YES
Comments:	YES
RSS Feed:	or Subscribe with .
Profile Page:	View profile page for Rick Overman

Blog post

Documentation, documentation and more documentation that is the focus. As you know we have been working hard here at GarageGames to make our engine more accessible and a big part of that is documentation. We have a lot of docs but they are scattered throughout the site, written by different individuals, using different techniques and styles. The result is document soup, not exactly the desired result.

Now it may sound like pulling this all together under one roof is an easy task, it is not. After a bit of research and lots of testing we have decided to convert all our documentation to docBook XML format. Unfortunately the DocBook tool chain is still under development so it has been a rocky road just finding the correct set of tools to use has been a challenge, they are still broken in places but they are close enough for now.

Robert Blanchet took on the challenge during his internship here at GarageGames and thanks to all his curses and long hours has our documentation project well underway. A preview of his efforts can be viewed here Torque DocBook Documentation Preview.

Please send all questions, comments and corrections to me.

Thanks,
--Rick

Recent Blog Posts

List:	12/19/06 - Scheduled Outage December 19th at 11am PST. 09/26/06 - A Good Problem to Have 06/02/06 - Goodbye Old Office :( 04/30/06 - What's up at GG? New MySQL servers and more... 04/03/06 - Want a Web Development Job at GarageGames? 02/13/06 - GarageGames.com AJAX'ified 02/09/06 - Be a Hero Answer A Question 12/22/05 - Website Update, Update

Submit your own resources!

Davis Ray Sickmon, Jr (Dec 17, 2003 at 02:09 GMT)

Dude! That is exactly what's been needed for a very long time! Glad to see GG pulling something like this together - I look forward to seeing the final product!
Can I put anymore !'s in this post?! ;-) (Does that reflect how excited I am about this? Or should I use more? :-)

Jarrod Roberson (Dec 17, 2003 at 02:59 GMT)

I have to say I am impressed, I did not go thru the content in detail but this will definately help lower the barrier to entry for lots of people.

David \"Fulcrum\" Wyand (Dec 17, 2003 at 04:40 GMT)

Greetings!

I'm VERY impressed with what you all have done. That right there represents a whole boatload of work. I look forward to seeing further iterations of the documentation.

It's also great to see you've mentioned the LightWave DTS exporter in there. :o) The next pass I do on my documentation, I'll keep in mind this work and see about producing something that could be integrated.

- LightWave Dave

Rick Overman (Dec 17, 2003 at 07:09 GMT) Resource Rating: 5

David - Writing docbook style docs is pretty simple, there is a small (but growing) example in Appendix D: HowTo Contribute to the Torque Documentation that will get people up and running in a matter of minutes (on a DSL). If you are interested I can set you up with the dev environment.

Owen "WDA" Ashcroft (Dec 17, 2003 at 12:21 GMT)

Impressed, already fought my way through Torque to learn a lot about it, but will definitly help those that are new, or don't have the patience to trace big parts of the engine to "see what happens next" thanks Rob, sure we will all learn new things from this project.

James Urquhart (Dec 17, 2003 at 15:25 GMT)

Having simple to write documentation sounds like a good idea.
Perhaps it will stop people from moaning about the "lack of" documentation?

p.s. don't forget about the Blender Exporter :)

Paul Dana (Dec 17, 2003 at 17:45 GMT)

Rick - there is interest in makeing a context sensitive help system
for the various Torque IDEs out there. Part of this task is technical - allowing symbols to be selectd in the IDE and then hoooking into the documentation, but part of it is how much the Doxygen docs for the classes and the rest of the documentation is oganized and cross referenced.

Part of what I would like to see is cross references to the other documentation from the Doxygen docs. The idea being that you could start with a symbol from some Class in the Torque codebase and go to a documentation page for that class and from there find cross refernces to related documentation.

Likely this sort of thint is already part of your thinking. After all every time Garage Games announces something...its already 10x smarter than what I would have thought of. I just mention this in case it influences your thinking in a good way.

Devon Ly (Dec 18, 2003 at 08:11 GMT)

Holy Crud!
Those are some really good topics in the doc.

Luc Jordan (Dec 19, 2003 at 14:11 GMT)

Hah! The LIST OF EXAMPLES kicks ass ^ 20.

I love you guys. :D

You must be a member and be logged in to either append comments or rate this resource.