Plan for Rick Overman
by Rick Overman · 12/16/2003 (4:52 pm) · 9 comments
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
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
#2
12/16/2003 (6:59 pm)
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. 
#3
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
12/16/2003 (8:40 pm)
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
#4
12/16/2003 (11:09 pm)
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.
#5
12/17/2003 (4:21 am)
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. 
#6
Perhaps it will stop people from moaning about the "lack of" documentation?
p.s. don't forget about the Blender Exporter :)
12/17/2003 (7:25 am)
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 :)
#7
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.
12/17/2003 (9:45 am)
Rick - there is interest in makeing a context sensitive help systemfor 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.
Torque Owner Davis Ray Sickmon, Jr
Default Studio Name
Can I put anymore !'s in this post?! ;-) (Does that reflect how excited I am about this? Or should I use more? :-)