Recommended change to document organization

#1 Which areas of the documentation are you referring to in this post?

We already have a seperate c++ engine reference and a seperate script reference. The DIF and DTS tools are documented seperately, too.

#2 I think what he's getting at is documentation from a "use case" perspective.

My team is still on the low side of the learning curve, and many times we've been saying to ourselves "man, if we just had a how-to on 'this'--we can dig through the rest of the code as we learn, but I KNOW this has to be easier than I'm doing it..."

Unfortunately, to find out that "easier way" usually means become at least a semi-expert on the underlying code/classes for what you want to do.

Use case documentation is outstanding for the new users, but I fully admit it's probably the hardest type to write and organize, because you have to put your head into that of a (relatively) new person, and not let -any- assumptions slide by.

An example of what I mean is the AdvancedCamera resource. I'm currently using it as a basis to write an "orbit cam" for our project, and while I have just about NO clue of the underlying quater math, vector manipulations, and zero understanding of the rendering layer as of yet, I'm able to code some pretty important functionality for our design by extending this "use case how-to" with a few (relatively) simple changes.

The GUI Editor documentation I think would greatly benefit from this style as well. Some folks have experience enough to know that a GuiBitmapButtonCtrl means that you use it when you want to have "pretty and interactive" buttons, but I look at that list of Ctrl types, and profiles, and I cringe trying to figure out which is best for a specific use.

Again, I fully understand how hard documentation is to write and track in the first place, and this is one of the hardest styles of documentation--but I would suggest that especially for resources, it's a great way for people to learn the engine small bites at a time, while still accomplishing things (once the use cases get large enough, anyway!).

#3 From my point of view - an experienced programmer who's new to Torque - I wish there were more How-Tos. Or rather, a concise, up-to-date list of the "good" How-Tos.

I think it's safe to say there are a LOT of great resources for using Torque. The trouble many of us new guys have is finding out which ones are still useful vs. old and possibly already integrated into the engine.

As an example, I've done searches for resources that were created back in 2001 and they worked great, giving me exactly what I was looking for. Other times, I'll find a resource from Dec 2003 and it won't work as explained OR the feature has already been integrated into the engine.

In many cases, if the FAQ were more up-to-date, it would really help a lot of out. As an example, there are numerous threads on the PathedInteriors for creating things like doors but I don't think anyone has really gotten them to work. For anyone searching for resources on getting a door into a mission, you'll end up searching/reading through about a dozen threads and a resource or two only to find out that there's no easy answer to getting this working.

I think the Essential Guide is one of the best starts to what the "beginner's guide" should be. It's a collection of the useful bits of the forums and resources combined into a concise, easy to find document.

The new Documentation page for Torque goes a long way to helping out - kudos to those involved!

One of the major problems I've encountered when using Torque - and maybe it's JUST me - is getting the "flow" a little better for getting new content into Torque. Creating an object in a 3D application and getting that into Torque seems a lot harder than it needs to be. I'll give 2 examples:

Quark: The documentation for Quark itself is pretty good. The documentation for getting Quark setup and getting things into Torque is also pretty good. Setting up textures could definitely use some more documentation as it's not always clear where files should go. Part of the problem is that there are too many references on how to do things when working with Tribes. I never played tribes so I'm at a disadvantage there. I think many of us "new guys" haven't used tribes for modding and many of us (most of us even?) could do without all the backward-compatability stuff.

Gamespace: Creating a MAP->DIF is a bit painful at the current time. Besides knowing how to create objects properly in Gamespace so they don't break when exported, you need to know a bit about map2dif to get things working right. Again, the textures might pose problems. While all of these can be worked out with a little trial-and-error, there is definitely room for improvement.

The main problem here is lack of a single, easy to follow document to get something created and exported. There are documents for creating things in 3D apps and there are docs to get things exported and there are docs to get things into Torque, but a simple walkthrough would be ideal.

One of THE major helps to all of the programmers would be to have a better search engine for the website. Ask ANY seasoned developer the importance of a good search engine and you'll get the same response - critical. Maybe you know the API call - search Google. Maybe it's a code snippet - load up the old project. But for Torque, you get a half-working search for the forums, resources, etc. that works mostly great for one word, but falls apart at anything more advanced.

I realize that it would take a lot of time to create from scratch a new search. Personally, I think it would be one of the best things GG could do for the community - heck, for its own team! I imagine many of the GG employees and interns have wanted to do searching across the forums to find info on certain topics.

-Nerseus

#4 To all,

Here is the problem:

Let's take Brian. It appears that Brian is working in a team with quite specialized roles. This seems to be the case because he wants his team members to be able to just read documentation specific to their particular role.

So, Brian is absolutely correct-- for his team, it makes the most sense to have the docs very much deliniated, in terms of layout and content, for particular roles (eg guides for interior modellers, scripters, engine programmers, etc).

Alright, sounds good. Since GarageGames wants to help indies in whatever way we can, and since we want to have great docs that help our customers, let's say we go this route and re-structure the docs so that they are very dileneated like this.

Now here's the problem. As soon as we do this, there will be a thread from somebody else saying something like:

Quote:I work in a very small team (or by myself), and the current docs really frustrate me.

Since I do everything, I have to go from building an interior, to exporting, to looking at the engine source to customize the export for this special stuff I do, to setting up the interior in the mission editor, to scripting some behavior for it... all almost at once! It sucks to have to jump back and forth between so many docs and wade through them to find the specific information I need at the time.

I mean, give me a walk-through. It's not that hard, and it makes a lot of sense to do things this way. Here's an example of what I need: I need to know how to set-up and texture a static model from Max. Talk in there about any performance issues I should keep in mind. (Since I'm a programmer and I can understand this stuff, it's best to have it here while I'm modelling, rather than missing it, and then having to go back and fix up my model after I read some notes in the engine docs about performance.)

Ok, I got my model set up. Now, walk me through the export process (and if you're really nice... include a talk about the exporter code and some links to resources in there, so I know where to dig if I need to change how the export works). Then tell me how to place this object in the Mission Editor. Also, tell me how to set up a trigger on the object and script a behavior for it. I mean, I do not want to have to read two freakin scripting chapters just to find this info. It should be right there in the mission editor stuff!

See how this flows so nicely together? It's just a step-by-step guide for creating static objects. Now, do the same for interiors, and animated objects, and all that. This would be so much better.

I am really disappointed with the way the docs are structured, it slows me way down.

You can see this is the polar opposite of what Brian's team needs. :)

Well, neither Brian nor the fictional wearer-of-many-hats above is going to be real satisfied with our current doc layout. The thing, is we really can't take it to either of these use-cases without alienating another whole set of users. And we do not have the man hours to spend time creating and maintaining a bunch of different structural schemes. We would rather spend that time creating new content, and I'm sure that most people would agree with that emphasis.

#5 Dan,

I agree, it'd be great to have a current list of how-tos and resource organization like that. We have talked and thought a lot about that very thing, actually. Presently, creating such an organization scheme is up on the whiteboard of ideas for possible things to work on. However, that may not get done for quite some time. It would require a lot of work, and as I'm sure you can imagine, we're very busy. :) The way things are now, it does take some work to find relevant resources-- but at least you can do so. As such, we feel there are more pressing matters to work on at the moment.

Likewise, better searching functionality is something that gets talked about a lot, and obviously we've spent a lot of time thinking about it carefully. Unfortunately, it is just not feasible at the present time, and you'll have to trust us on that. If or when we do a major restructuring of the site, incorporating advanced searching capabilities throughout will no doubt be a major concern. But such a major overhaul is probably quite a ways away. The present system works well enough, though we recognize of course that it's not perfect. Again, since it works alright now, there are just more important things to focus our time on at the moment.

To all: anyway, we appreciate the feedback on docs, and I hope it doesn't sound like we don't. These are all good suggestions. I hate to say "we just can't do it" very much at all, but sometimes you have to. I hope these explanations at least make it clear why. But hopefully you all know that we try our best not to say that, and we always think very carefully about suggestions before deciding how best to act on them.

#6 Hey Josh,

I think what brians is trying to get at is he is looking for some short a sweet docs for experianced people. I know how to do it myself but how do I do it working with Torque. The documentation is great and is really detailed but will also take someone a long time to read :).
There are a lot of people (especially experianced programmers) that really don't want to read about how to do a for loop and read for a while :). They want something that just gives a quick overview and they can figure it out of themselves.
Is there a way to do this with TGE? Well, I have no idea, I have been thinking about it but haven't come up with anything yet. TGE is huge and it has a learning curve for the best programers.

Later, Ben

#7 Some example usage would have been very useful for me at the beginning. Just a few examples for each technology. At the start, this wouldn't even need to be descriptive, just a list... like: interiors are good for buildings and structures, and any static object that will benefit from better lighting. Perhaps that can be part of the focus for your "new content." Much of this is covered in the forums already, but it can be difficult to find, since some topics that cover such things are titled something like: "Can I ask a question?" or "n00b here..." One thing I have done along the way is "captured" any forum thread or resource I thought might be useful for what I am doing, or will be doing. I simply copied the link of the thread or resource page and emailed it to myself. Maybe it's time to compile this as a resource...it's been about a year.

#8 John, it would be great to see that as a resource. :) Regarding your example usage... example.. actually there is a section in the docs that says exactly what you're asking for, if I'm reading your post correctly. Actually there are a few sections that cover that. A very quick overview in the getting started section, and then more specific details about the difference between interiors (DIFs) and DTS-objects in the Max/DTS chapter, even more details in the Quark/DIF chapter.

Ben, I see what you're saying. Yeah figuring out at what level to target documentation is a hard problem. At present, we've had to just focus on trying to help the largest number of people possible (which means trying to make it pretty easy on people without a lot of experience), because we don't have the man-hours to create specialized versions for particular experience levels. It would be awesome to have the ability to target the docs at different experience levels, just like it would be awesome to target the docs at different kinds of use-cases, but it's simply a case that we don't have the time to do that *right now*.

That said, we do have some things in the work to address this particular issue (actually, Ben, you already know about some of this ;). Hopefully within the next few months there actually will be some targetted delivery going on with the docs. For now, more advanced users can get by pretty well by looking at stuff like Joel Baxter's quick reference and skimming the official docs for what they need. But yeah, this situation will be even better in the future.