Is there any point to write new TDN articles?

#1 Not really. We'll see what happens when the steering committee is assembled, and the hovering military base is launched.

#2 Sounds like a long term project *sigh*

Do you know if GG will produce any sensible and structured documentation or are they expecting the community to create another unstructured mess of sporadic documentation?

Well, at least we can hope to get a better search engine for it.

#3 The repo has a wiki system. I think the best place for engine-specific stuff is there. A common wiki for TorqueScript would also be useful, but simply using GitHub's wiki already gives us better search than they have on the website here. It's just a matter of transplanting what's worth keeping from TDN, and rewriting where necessary.

I expect the steering committees top 5 items will include how this should be organised, so I'd wait with doing anything. But it doesn't hurt to start a wish list/discussion about the documentation.

The parts I feel are weakest, apart from everything in the way of examples being outdated (many times over!), are the internals. Getting started on completely ignoring script, extending script, subclassing innards to make cool new objects - all of that could use some focused docs.

Then there's the fact the new engine is, well, *new*, so everything needs rewriting. I'm sure that's part of the overhaul, though. If so we're getting PDFs and webpages for the different data formats and how to script them, eventually. It looks like the focus is on getting a working engine first, though.

Tutorials are the next big thing to create then, and will probably fall largely on the community. Mich & Melv probably have some material to get started (and the sandbox in the MIT release is a good basic project to look at), but lots needs to be written.

There's a lot of new stuff for everybody to get used to, but I'm sure we could all get a decently stocked documentation wiki up and running within a couple of months.

#4 I think Mich mentioned that all of the internal GG engine documentation would be ported over to the Github wiki for Torque 2D. As an example I've seen the docs for the asset system, it's well written and very detailed.

Some general thoughts:

If I understand the Github wiki system correctly, write access is limited only to those with repo write access which will be quite a limited number of people from GG/the steering committee. You would have to download a local copy of the wiki, make the changes you wish, and then submit a pull request to get the master wiki updated. While it seems like a decent way to curate and control the docs, I don't know how much involvement it would promote - seems like a lot of hoops to jump through compared to the easy web editing a MediaWiki site (like TDN) has.

TDN itself seems like it is only being kept on life support so the old docs don't disappear - it is using a really old version of MediaWiki and image uploading has been disabled. TDN does show the drawbacks of a wiki that is not actively maintained, as it can quickly degenerate into a big mixup of current and outdated info, lots of different article formats, poor searching, etc.

Torque 3D has a documentation repo, which looks like it is a collection of the html pages from the online/offline docs that came with T3D v1.2. The big drawback for T2D is that a lot of the previous online/offline docs that come with v1.7 or now 1.8 will no longer be valid.

Hopefully with a bit of planning tutorials and engine documentation can be written in such a way that each new release doesn't cause a huge amount of rewrite work. The "create a basic game from scratch" tutorials are always interesting but seem to suffer the most when new features are added or changes are made to the engine. Especially when editors are involved.

Personally, I've hosted a TGB video tutorial website for the past 3 years and plan to create some tutorials (both written and video) for the MIT release as I go along learning the engine. I'm certainly willing to open up my site for other community submitted content as well.

#5 We'll see what GG can do about a location for a more open wiki when T2D is out, then.

Extra documentation people would probably like: HOWTO entries for all sorts of tasks (would tie together knowledge which is probably far apart in the official docs), a tutorial on every object, asset import guides.

#6 Okay, seems like I should sit and wait for a while...
Is there any updated documentation for the new TGB 1.8 somewhere?

#7 No updated docs as far as I know, this release was just to update the platform code and fix some bugs so those in the middle of making games with TGB can finish them.

#8 I can't build with the 1.7.6 settings on Xcode either. :'( Anyone else know the proper build settings?

#9 I'm pretty much in the practice of digging through the engine source when I need to find out how something works....

#10 The engine source doesn't have the build settings, though... does it?

#11 I have been toying with the idea of building my own doc resource on my domain. One thing I wanted to do was create a GreaseMonkey plugin that I can use to publish article links I find on GG onto my own database to help me find things again.

One thing that bugs me is digging through the forums to find some tweak made on an engine to make a feature work for a newer version of that engine.

The problem I have with docs is the engines change and the docs get stale. What would be better would be a suite of code examples that get tested with the engine. Then if something breaks you can see that. Almost like a unit test for common features. For T3D Render To Texture would be a good example of a feature that could be in this category.

#12 @Frank I had exactly the same idea :)

To build my own Wiki and fill it with useful code examples and documentation. I haven't found any Wiki I like so far...

#13 If you want I could start one up. I will search for a simple wiki. One issue we will have to watch out for is spamming. I will look around and see what I turn up. I can create a Torque subdomain and stuff everything in there.

#14 It would be nice to try to save the knowledge in TDN and forums in one organised place. However, I don't think I have the time to put too much effort into a transfer and somehow we need to keep things organised.

A wiki system that would force us to use the same template and automatically do the indexing would be a great help. We also need to detect duplicitous articles to not have the same subject spread out over several "isolated" articles.

I guess you are familiar with the stackexchange platform. I think it is a great platform but I miss the blog or an article function. I don't know if there is one available for it although.

In terms of organisation I was thinking to mix it with source and script documentation. For example:

Scripting: function t2dSceneWindow::onMouseDown(%this, %modifier, %worldPosition, %clicks)
C++: void t2dSceneWindow::onMouseMove( const GuiEvent& event )

Description
Callback function for left mouse button down messages. Bla bla bla...

Examples:

Script example:

function t2dSceneWindow::onMouseDown(%this, %modifier, %worldPosition, %clicks)
{
  echo("Left mouse button down with modifier mask "@%modifier@" in scene window object: "@%this@" at world position "@%worldPosition@". There has been "@%clicks" since last event call.");
}

C++ Example:

void t2dSceneWindow::onMouseMove( const GuiEvent& event )
{
    // Do your thing
    
    if( something )
    {
      // Propagate Mouse Event.
      dispatchMouseEvent("onMouseMove", event);
    }
}

Related articles:
bla bla

#15 I have space and a perfect wiki setup. I've tried a ton[1] of wiki systems, and good old Dokuwiki is still giving the best results for actual documentation (indexing, export to other formats, plugin availability).

I have asked Mich if GG have any plans regarding a wiki, or if they want to point a subdomain in the right direction. If they're just going to kill off TDN we have other options ready to go. The code must flow.

[1]Yeah, all the candidates take a frickin' gigabyte when you add up all their requirements.

#16 I brought the topic up in one of our recent meetings. It was actually the T2D and T3D steering committees coming together for the first time to talk about the future. TDN is no longer viable and will just confused users of T2D 2.0 (MIT). I still think a wiki is the best way to go for community based documentation, but I think the following requirements are necessary to avoid the decay we experienced with TDN:

1. Easy to access. Ideally, embedded on GarageGames.com's main site
2. Dedicated moderators. Anyone can write docs for the wiki, but we need people who are responsible for maintaining the organization and quality of the wiki
3. Standardization. Wiki articles should adhere to the same layout, formatting, and structure. If an article has good content, but does not adhere to the standardization, someone (see #2) needs to swoop in and fix the structure.

I saw Ronny's e-mail and I will bring it up in the next meeting.

#17 Excellent. I think you'd love Dokuwiki[1] - automatic ToCs, Epub/PDF export via plugins, reasonably pluggable authentication backend (could use GG accounts) and independent ACLs.

A couple of moderators per section (whatever the sections may be - per engine, per platform, per concept, per submodule, per language) would be a good idea. A bit of overlap in skills is needed to verify contents. Keeping a decent structure is easy enough, especially if we are going to completely ignore the old engines. T3D has more useful content by percentage, which would need to be transferred.

[1]Why not MediaWiki? Many reasons - the extra features out of the box in Dokuwiki are more useful for documentation, and the security model in classic wikis is pretty weird. MediaWiki users are pages. Doesn't integrate as easily with classic database-enabled login mechanisms. I'm sure keeping TDN working is hell.

#18 Might I throw out there that this time around it would also be nice if the official documentation (tutorials) were kept a bit more up-to-date, and also had their character encoding checked to make sure some of the problems with this current site don't happen. It might be just me, but I ran into several instances a year ago trying to learn how to use T2D where the documentation was old, incorrect, or the character encoding on some of the symbols was not correct, requiring me to look at the local files instead to find out what to type.

#19 Yeah, this site isn't quite ready for anything outside *some* punctutation, 0-9 and a-z. A modern wiki would ensure that's OK, though :)

#20 If you are having issues with entering stuff into the site because of character bugs then check out this resource:
Wonky Text Fixer