by date
The Future of the TGB Documentation
The Future of the TGB Documentation
| Name: | Matthew Langley |  |
|---|---|---|
| Date Posted: | Nov 05, 2006 | |
| Rating: |  4.9 out of 5 | |
| Public: | YES | |
| Comments: | YES | |
| RSS Feed: |  or Subscribe with  . | |
| Profile Page: | View profile page for Matthew Langley |
Blog post
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 <h*> 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 <h*> 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.
Recent Blog Posts
| List: | 11/30/06 - Torque Game Builder 1.1.3 Goes Live! 11/05/06 - The Future of the TGB Documentation 05/16/06 - TGB Bounties Extended! 05/12/06 - Final review of TGB Bounties today 05/04/06 - Call to the TGB Community 02/28/06 - New TGB Particle Editor (Preview) 02/06/06 - A lot has happened 12/09/05 - Preview of a TDN T2D Strategy Article |
|---|
Submit your own resources!| David Montgomery-Blake (Nov 05, 2006 at 20:40 GMT) |
| Stefan Lundmark (Nov 05, 2006 at 20:46 GMT) |
| Allyn "Mr_Bloodworth" Mcelrath (Nov 05, 2006 at 20:57 GMT) |
Looks great.
| jydog (Nov 05, 2006 at 21:09 GMT) |
Thanks
| Tom Perry (Nov 05, 2006 at 21:14 GMT) |
| Tom Eastman (Eastbeast314) (Nov 05, 2006 at 21:38 GMT) |
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!
| Alienforce (Nov 05, 2006 at 21:59 GMT) |
| NUTS! (Nov 05, 2006 at 22:07 GMT) |
| Tom Bentz (Nov 05, 2006 at 22:36 GMT) |
| Matthew Langley (Nov 05, 2006 at 23:19 GMT) Resource Rating: 5 |
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.
Edited on Nov 05, 2006 23:21 GMT
| Terry (Nov 06, 2006 at 04:28 GMT) |
| David Higgins (Nov 06, 2006 at 05:45 GMT) Resource Rating: 4 |
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? :)
| Mark McCoy (Nov 06, 2006 at 08:24 GMT) |
| Dmitriy Kazimirov (Nov 06, 2006 at 08:36 GMT) |
| Steve Flowers (Nov 06, 2006 at 11:46 GMT) |
| Ian \"Xest\" Winter (Nov 06, 2006 at 14:14 GMT) |
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?
| Keith Johnston (Nov 06, 2006 at 14:30 GMT) |
| Daniel Staub (Nov 06, 2006 at 14:53 GMT) Resource Rating: 5 |
Sammual
| Unsung Zero (Nov 06, 2006 at 16:32 GMT) |
Not enough free time: This makes me sad :[
| Firas (Nov 06, 2006 at 16:53 GMT) |
| Ed Averill (Nov 06, 2006 at 17:14 GMT) |
Excellent news.. I'm really enjoying TGB and improved documentation will only make me happier!
| Matthew Langley (Nov 06, 2006 at 17:53 GMT) Resource Rating: 5 |
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.
| Gary Patterson (Nov 07, 2006 at 01:03 GMT) Resource Rating: 5 |
Thanks for focusing on the docs!
| Ian \"Xest\" Winter (Nov 07, 2006 at 10:23 GMT) |
| Jeremy Alessi (Nov 07, 2006 at 14:52 GMT) |
| Pisal Setthawong (Nov 08, 2006 at 02:25 GMT) |
Edited on Nov 08, 2006 02:26 GMT
| Bob (Nov 08, 2006 at 06:32 GMT) Resource Rating: 5 |
| Hokuto (Nov 10, 2006 at 16:22 GMT) |
| amaranthia (Nov 13, 2006 at 07:01 GMT) Resource Rating: 5 |
| David Higgins (Nov 13, 2006 at 07:46 GMT) Resource Rating: 4 |
| Matt Harpold (Nov 16, 2006 at 09:33 GMT) |
You must be a member and be logged in to either append comments or rate this resource.
