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.
#2
11/05/2006 (12:46 pm)
Woohooo! 
#3
Looks great.
11/05/2006 (12:57 pm)
Incredible!, but i cant stress enough that tutorials need to be made. Step by step assuming the user knows nothing tutorials.Looks great.
#4
Thanks
11/05/2006 (1:09 pm)
I know documentation is a pain and takes time away from "more important" projects, but it is needed for many of us learning the system.Thanks
#6
was completed last night, maybe I'll be able to get back to working on the docs :)
I've been blown away by how much better the docs are now. No more need to have Acrobat open (with its crappy search) - now we can use the browser search to find stuff in the reference. And the breakout tutorials mean that tutorials are more to the point - with step-by-step details if you need them. They're flippin' sweet, Matthew!
11/05/2006 (1:38 pm)
And now that I've been blown away by how much better the docs are now. No more need to have Acrobat open (with its crappy search) - now we can use the browser search to find stuff in the reference. And the breakout tutorials mean that tutorials are more to the point - with step-by-step details if you need them. They're flippin' sweet, Matthew!
#7
11/05/2006 (1:59 pm)
GREAT! Keep up the good work!
#10
With the Reference and Glossary cross-referencing I'm just beginning to realize how much this will change working through the docs. Say your in a tutorial and the word "bounding box" is mentioned... you aren't completely sure about it so you hover over it (since it's an obvious blue color) then you see a tooltip with "Terms: Bounding Box"... you click it and right there your definition appears straight from the reference.
The same goes for function and methods and even with Component (breakout) tutorials... such as "Create a Project" demonstrated in the picture. This means tutorials are smaller without all those complex definitions and you can get all the info you need right at your fingertips, this really is changing the way we design tutorials and the way you go through them... hopefully now you will never run accross a term that you don't understand or a method/function you don't know the usage for while going through a tutorial.
@Allyn: have you gone through the TGB Documentation before? I noticed you don't have a TGB license so just wanted to point out this is presently only for TGB and all the docs you see in that ToC in the images are not mock, they are real and most of them already exist though now are being heavily overhauled. We are adding some even more entry level tutorials (can any say Hello World :)) as well to work people into the make a small game tutorials.
11/05/2006 (3:19 pm)
Glad everyone's liked it so far :) This is what I've been pouring my time, creativity, and effort into for a little while now. I'd like to add (just in case there was confusion) that this is all in html and completely replaces the existing PDF files (as Eastbeast mentioned). This will be completely on your computer to browse at will...With the Reference and Glossary cross-referencing I'm just beginning to realize how much this will change working through the docs. Say your in a tutorial and the word "bounding box" is mentioned... you aren't completely sure about it so you hover over it (since it's an obvious blue color) then you see a tooltip with "Terms: Bounding Box"... you click it and right there your definition appears straight from the reference.
The same goes for function and methods and even with Component (breakout) tutorials... such as "Create a Project" demonstrated in the picture. This means tutorials are smaller without all those complex definitions and you can get all the info you need right at your fingertips, this really is changing the way we design tutorials and the way you go through them... hopefully now you will never run accross a term that you don't understand or a method/function you don't know the usage for while going through a tutorial.
@Allyn: have you gone through the TGB Documentation before? I noticed you don't have a TGB license so just wanted to point out this is presently only for TGB and all the docs you see in that ToC in the images are not mock, they are real and most of them already exist though now are being heavily overhauled. We are adding some even more entry level tutorials (can any say Hello World :)) as well to work people into the make a small game tutorials.
#11
11/05/2006 (8:28 pm)
Very nice work, Matthew, and thanks for the update... 
#12
I love the look, can't really say much about the feel cause every time i click on the [+] in the pictures nothing happens -- go figure, eh? :)
11/05/2006 (9:45 pm)
Matt -- looks great, I can't wait to get my hands on easier to navigate documentation -- some additional tutorials would be great too, but I try not to ask for too much :)I love the look, can't really say much about the feel cause every time i click on the [+] in the pictures nothing happens -- go figure, eh? :)
#13
11/06/2006 (12:24 am)
Matt is my hero.
#14
11/06/2006 (12:36 am)
What about creating such good all-in-one documentation for TGE/TSE?
#15
11/06/2006 (3:46 am)
I second Dmitriy's sentiment:)...
#16
Of course jumping into a 3D engine is generally a bigger step, and of course you can't integrate most the tools needed into a 3D engine as easily (or quickly or cheaply for that matter) as you can a 2D engine but particularly in terms of docs/tutorials/examples - can we expect these to eventually be equal in quality to TGB?
11/06/2006 (6:14 am)
Matthew, the new documentation looks great but as mentioned by the above two posters is there any reason why TGB seems to get so much more of a polishing than TGE/TSE? TGE certainly seems like it's moving in the right direction with integration of TLK and some of the merges of the UI components into TGE the last couple of builds but as a whole TGE/TSE "feel" far more neglected than TGB. 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? TGB just feels like a really nice polished product that fulfills the game building for everyone vision as there is a clear path set for those starting out with the product in terms of docs, tutorials and tools. Of course jumping into a 3D engine is generally a bigger step, and of course you can't integrate most the tools needed into a 3D engine as easily (or quickly or cheaply for that matter) as you can a 2D engine but particularly in terms of docs/tutorials/examples - can we expect these to eventually be equal in quality to TGB?
#17
11/06/2006 (6:30 am)
This looks fantastic! I have one suggestion - would it be possible to also have a link from the API's back to one of the demos? I often find it useful to see an example of how an API is used to understand it.
#18
Sammual
11/06/2006 (6:53 am)
As someone who will be getting TGB when his next paycheck comes in - Thank you.Sammual
#19
Not enough free time: This makes me sad :[
11/06/2006 (8:32 am)
New documentation: This makes me happy!Not enough free time: This makes me sad :[
Associate David Montgomery-Blake
David MontgomeryBlake