The Future of the TGB Documentation
by Matthew Langley · 11/05/2006 (12:31 pm) · 31 comments
The future of the TGB Documentation
Since a picture is worth a thousand words, let me first post a picture.
This is the new face of the TGB Documentation (note: the visuals in all of these pictures may and probably will be be updated before release). Here is a list of featurs the new documentation supports (I like to call the Torque Documentation Framework).
Features:
- The entire doc base can be accessed and navigated through a single interface (no folder scouring anymore).
- Full Table of Contents with headers and sub-headings expandable and collapsable.
- Table of Contents tool tips for each document listed.
- Autogenerated hub pages for each tutorial set.
- What I like to call "Component Tutorials"... basically "stub" or "breakout" tutorials that are in a seperate tutorial file (such as "Create a New Project") that can be easily linked into any documents.
- Multi-Page Search of the entire doc base with a single word and psuedo phrase match.
- Searched page word highlighting, with add/remove highlighting options.
- Document versioning, this is an internal feature that won't affect users much, though it will help insure we only build the proper docs for the proper release.
- The entire docbase is parsed for TGB Reference and Glossary methods and terms to stub in dynamic links that you can click to get definitations (pictures represent this much better, definately my favorite feature).
Ok now that a breif description of each new feature is listed, lets see some pictures!
Full Table of Contents with headers and sub-headings expandable and collapsable
As you can see there are headings and sub headings. On the internal end of this every tag is parsed out and properly logged. Here is a great example of this working with the Glossary and entire TGB Reference.
Table of Contents tool tips for each document listed
When you hover over a document listing in the ToC (Table of Contents) a tooltip will appear (if there is one) describing the tutorial.
What I like to call "Component Tutorials"... basically "stub" or "breakout" tutorials that are in a seperate tutorial file (such as "Create a New Project") that can be easily linked into any documents
Now this is one of the most exciting new changes... the impact this will have on the docs is immense. Presently we are still very busy stubing out "Component Tutorials". Once we finish the tutorials will be a great deal shorter with all of the repetative section in easy to click stubs in case you need it.
Here you will see the text "If you're unsure on how to do this click here." underlined.
If you then click that text this will slide open below it.
No messy links, you simply click the text and the stub (component) tutorial appears right in front of your eyes.
Multi-Page Search of the entire doc base with a single word and psuedo phrase match
Another of my favorite features. Multi-Page searching... there is a search box in the top right while you navigate the doc base. You can simply type a word into it then hit the enter key or click the spyglass.
Then you will be presented with the search results page.
Searched page word highlighting, with add/remove highlighting options
Now if we click the "Static Sprites" tutorial the tutorial page will appear and the document will highlight our searched word(s) with a nice little highight progress bar.
The entire docbase is parsed for TGB Reference and Glossary methods and terms to stub in dynamic links that you can click to get definitations
Saved the best for last. This is definately my favorite feature (as well as the trickiest to implement and debug). All methods from the TGB Reference and terms from the Glossary are parsed out of the entire docbase. What this means is if you run accross onLevelLoaded() in the docs it will be red. If you hover over it you will get all versions of onLevelLoaded in a tooltip. If you click a version the definition will appear for you! A visual representation is much better.
All of the red words are methods that you can get definitions for.
The same works for Glossary terms, though they appear as blue.
Well hopefully this reassures any TGB users that we are indeed working on the TGB Documentation. In fact we are heavily working on it (as you can see). This Doc Framework is getting close to finished though some visual appearance still needs to be worked on and some issues still dealt with. The beauty of the system is the entire resulting documentation folder is auto-generated from the source one based on multiple parsers and the entire Table of Contents is auto-generated.
This also means the entire TGB Doc Base is moving to html files so keeping TDN in sync with it will be a much easier task.
Since a picture is worth a thousand words, let me first post a picture.
This is the new face of the TGB Documentation (note: the visuals in all of these pictures may and probably will be be updated before release). Here is a list of featurs the new documentation supports (I like to call the Torque Documentation Framework).
Features:
- The entire doc base can be accessed and navigated through a single interface (no folder scouring anymore).
- Full Table of Contents with headers and sub-headings expandable and collapsable.
- Table of Contents tool tips for each document listed.
- Autogenerated hub pages for each tutorial set.
- What I like to call "Component Tutorials"... basically "stub" or "breakout" tutorials that are in a seperate tutorial file (such as "Create a New Project") that can be easily linked into any documents.
- Multi-Page Search of the entire doc base with a single word and psuedo phrase match.
- Searched page word highlighting, with add/remove highlighting options.
- Document versioning, this is an internal feature that won't affect users much, though it will help insure we only build the proper docs for the proper release.
- The entire docbase is parsed for TGB Reference and Glossary methods and terms to stub in dynamic links that you can click to get definitations (pictures represent this much better, definately my favorite feature).
Ok now that a breif description of each new feature is listed, lets see some pictures!
Full Table of Contents with headers and sub-headings expandable and collapsable
As you can see there are headings and sub headings. On the internal end of this every
Table of Contents tool tips for each document listed
When you hover over a document listing in the ToC (Table of Contents) a tooltip will appear (if there is one) describing the tutorial.
What I like to call "Component Tutorials"... basically "stub" or "breakout" tutorials that are in a seperate tutorial file (such as "Create a New Project") that can be easily linked into any documents
Now this is one of the most exciting new changes... the impact this will have on the docs is immense. Presently we are still very busy stubing out "Component Tutorials". Once we finish the tutorials will be a great deal shorter with all of the repetative section in easy to click stubs in case you need it.
Here you will see the text "If you're unsure on how to do this click here." underlined.
If you then click that text this will slide open below it.
No messy links, you simply click the text and the stub (component) tutorial appears right in front of your eyes.
Multi-Page Search of the entire doc base with a single word and psuedo phrase match
Another of my favorite features. Multi-Page searching... there is a search box in the top right while you navigate the doc base. You can simply type a word into it then hit the enter key or click the spyglass.
Then you will be presented with the search results page.
Searched page word highlighting, with add/remove highlighting options
Now if we click the "Static Sprites" tutorial the tutorial page will appear and the document will highlight our searched word(s) with a nice little highight progress bar.
The entire docbase is parsed for TGB Reference and Glossary methods and terms to stub in dynamic links that you can click to get definitations
Saved the best for last. This is definately my favorite feature (as well as the trickiest to implement and debug). All methods from the TGB Reference and terms from the Glossary are parsed out of the entire docbase. What this means is if you run accross onLevelLoaded() in the docs it will be red. If you hover over it you will get all versions of onLevelLoaded in a tooltip. If you click a version the definition will appear for you! A visual representation is much better.
All of the red words are methods that you can get definitions for.
The same works for Glossary terms, though they appear as blue.
Well hopefully this reassures any TGB users that we are indeed working on the TGB Documentation. In fact we are heavily working on it (as you can see). This Doc Framework is getting close to finished though some visual appearance still needs to be worked on and some issues still dealt with. The beauty of the system is the entire resulting documentation folder is auto-generated from the source one based on multiple parsers and the entire Table of Contents is auto-generated.
This also means the entire TGB Doc Base is moving to html files so keeping TDN in sync with it will be a much easier task.
About the author
Was a GG Associate and then joined GG in 2005. Lead tool dev for T2D and T3D. In 2011 joined mobile company ngmoco/DeNA and spent about 4 years working game and server tech. 2014 joined startup Merigo Games developing server technology.
#22
There is not much I can say officially, though what I can give you is a bit of our perspective and views on the matter. We view TGB as the perfect test bed for future GG development. Since it's a 2D (world) environment the development is quicker so it functions as a better test bed for things such as highly polished documentation and a doc framework. We definately are planning on using what we've learned and yet to learn with TGB and apply it towards TGE and even TSE. Though one thing we do view is the different levels of each product. TGB is a much more entry level product so will always be easier to use and the tools will be more refined and focused on ease of use. TGE is somewhat middle grounds, a bit higher entry level though we still intend it to be easy. TSE is a much higher entry level and our goal is to be the next gen solution.
I guess what I'm saying is that we plan on applying the same level of polish to all of our products (using TGB as a perfect test), though they will be applied differently with varying levels of "ease of use" as a focus. As far as TGE docs, we will hopefully be addressing these to a limited extent in the near future thoguh no promises... hopefully this reassures you even though I cannot give you any hard information.
@Firas:
We are 'hoping' to release TankBuster source scripts with the next TGB release, no promises though since there are a couple things that have higher priority, though it is definately up there :) In fact doing a final pass on it for demo release will probably be one of the things I do once I finish with most of this framework.
11/06/2006 (9:53 am)
@Ian:Quote:
Is this something GG is looking at? Can those of us who prefer the 3D world expect to see TGE/TSE brought upto par with TGB in terms of the polish they get?
There is not much I can say officially, though what I can give you is a bit of our perspective and views on the matter. We view TGB as the perfect test bed for future GG development. Since it's a 2D (world) environment the development is quicker so it functions as a better test bed for things such as highly polished documentation and a doc framework. We definately are planning on using what we've learned and yet to learn with TGB and apply it towards TGE and even TSE. Though one thing we do view is the different levels of each product. TGB is a much more entry level product so will always be easier to use and the tools will be more refined and focused on ease of use. TGE is somewhat middle grounds, a bit higher entry level though we still intend it to be easy. TSE is a much higher entry level and our goal is to be the next gen solution.
I guess what I'm saying is that we plan on applying the same level of polish to all of our products (using TGB as a perfect test), though they will be applied differently with varying levels of "ease of use" as a focus. As far as TGE docs, we will hopefully be addressing these to a limited extent in the near future thoguh no promises... hopefully this reassures you even though I cannot give you any hard information.
@Firas:
We are 'hoping' to release TankBuster source scripts with the next TGB release, no promises though since there are a couple things that have higher priority, though it is definately up there :) In fact doing a final pass on it for demo release will probably be one of the things I do once I finish with most of this framework.
#23
Thanks for focusing on the docs!
11/06/2006 (5:03 pm)
As a brand-new TGB licensee, I'm working through the tutorials and still trying to get my head around the concepts. A lot of it is straightforward, but I'm finding the GUI stuff particularly tricky at the moment. New documentation is perfect for helping people like me. Thanks for focusing on the docs!
#24
11/07/2006 (2:23 am)
Thanks Matthew, what you said certainly makes sense :)
#25
11/07/2006 (6:52 am)
Yes HTML ... this was desperately needed! Will the docs be accessible right from the TGB environment AND Torsion? ;) 
#26
11/07/2006 (6:25 pm)
The new docs for TGB is simply getting better and better. Thanks, it makes me happy to be a TGB owner!
#29
11/12/2006 (11:01 pm)
Hey Matt, any chance that the GUIs will be documented? 
#30
11/12/2006 (11:46 pm)
@Amaranthia, now your asking for too much there :)
#31
11/16/2006 (1:33 am)
Oh my god awesome. :D 
Torque Owner Ed Averill
Excellent news.. I'm really enjoying TGB and improved documentation will only make me happier!