What you want in Documentation?

#41 Transparent Development, Torque 2, and You!

#42 I don't want to beat a dead horse. But I feel the need to chime in once again and request that 100% of all efforts be focused on the TGB reference until it is, umm, useful. There is nothing more frustrating than searching through documentation to find the equivalent of:

doSomething(opt1, opt2, opt3, opt4)

params
   opt1, opt2, opt3, opt4 : These are parameters.

This is the default answer I get on a large amount of my adventures into the documentation. They lack even the most basic description of what the function does. A single statement that is self-referential is a waste of time. For example:

getInternalName()
Description: getInternalName returns the objects internal name

OK. What is an Internal Name? There is no link to get a further explanation. I also find immediately underneath that...

getName()

It doesn't even say the completely useless phrase, "Description: getName returns the objects name" So how does InternalName differ from Name?

Sure I can guess. Sure I can look elsewhere. But the Reference should be THE PRIMARY source of information.

I also confess that I am used to language reference materials from Borland/Code Gear, Microsoft, and Sun. But TGB is a vastly simpler product, and it is not unreasonable to expect a solid basic reference manual, even if it is only resourced by single individual.

Yes, features are nice, but please document fully what you have first. In the mean time, I am fortunate to have access to the source code.

Thanks GG for doing your best. It is appreciated.

#43 Use the 1.1.3 documentation. Not the current 1.5.1.

#44 Chaim:
Do you see potential in the users creating that documentation, by utilizing something like a Wiki?
I know there are many times that I would like to edit typos and misinformation that I find in the docs, but it's not very convenient. If there were a Wiki-style "edit" link above each section, I could not only save myself the trouble of misunderstanding that doc in the future, but my learning and examples could be passed on to others.

--clint

#45 Clint,
Where to start? If you are asking will it happen, I would put all my money on no. If you ask me if could it happen, I would say yes, under the proper leadership.

There are many things that come into play in this situation. I'm not sure I could describe them all in a single message board post, so let me just provide a short ramble and describe how it could happen.

Somebody on the paid staff is given the job of recruiting, organizing, and leading (by example) a fairly large group of volunteers. That staff member will need a budget. They will have to incentivize the project via gifts and special privileges to get enough quality participation. The staff member will need to put together a structure, preferably one that has been proven by some other product/community, within which the volunteers would work. For example, there would need to be some means of directing work to get good coverage of all of the objects and methods at a base level before people go off and start creating elaborate articles on the more interesting topics. There would be a role for QA - preferably somebody with real world editorial experience. There would need to be an invite-only private forum for the active volunteers to socialize as well as conduct "business". And this would produce good wiki-based documentation. However, this wouldn't be able to be leveraged into decent "printed" documentation. (By "printed" I mean .DOC, .PDF, or .CHM files) That would require a whole different approach using something like you would see in a technical publications department with source documents under version control, content separated from presentation, etc. Something of that extent is almost without a doubt, going to require a paid staff.

#46 Believe it or not documentation is in fact a huge priority for us in the present as well as the future. Though we won't likely push the official documentation to a wiki, we have considered a web implementation much like php.net, in which community members can post comments about fixes, changes, and additional examples.

This thread and further suggestions are great. Feel free to continue down any road you feel is appropriate, though keep in mind that the larger ideas may be considered for the future but probably is not going to happen soon. Though the smaller suggestions, such as documentation that's smaller, more engaging, more based around concepts, more complete reference, etc... are a huge benefit. Also things you stumbled on at first, even a list. Things like this is invaluable, back when I was a new TGB user was long before there was even a tool, so it's very hard for me to figure out those stumbling blocks at times... giving us that information gives us an idea what we need to cover in beginning tutorials.

#47 I think the documentation, in addition to needing improvements in content, needs to be cleaned up visually. HTML isn't so bad, but javascript and frames are obstacles to readability. Popping up an invisible DIV for supplemental information is no easier than linking to another document or an anchor, and only adds unnecessary complexity. Simplify the interface as close to plain text as possible. PDFs are fine, but HTML+CSS is at least as printable if designed correctly.

#48 I've been a member here for almost 2 years now and documentation has always been something that I felt has held your products back from being even better than they are now. I'm very glad to see you guys are making a stronger push in that direction. I do think a Wiki (a real wiki, not TDN) that the community can keep updated in addition to you is the best option.

I really need 2 types of info that I have a hard time finding right now:

1. Hooking in an external datasource such as SQL or Access with a TGB game.

2. Doing things in code rather than TGB. Some of us either can't or would rather not use the TGB Editor to make our entire game. For me the TGB editor, and like all tools its great in some instances but not a 1 tool for all solution, at least not for me. For instance, my game genre is sports and I don't know what 2 teams the gamer is going to choose so I need to be able to load the images and animation objects from code. I would love a simple tutorial that covers doing all of the basic things such as loading an image, loading an animation, etc... using only Torquescript.

#49

Quote:
I do think a Wiki (a real wiki, not TDN)

Could you explain what you mean by this? TDN is driven by Mediawiki, so I'm not really sure what you mean when you imply that TDN isn't a real wiki.

#50 I think AI is an important aspect of most games, especially platformers. My recommendation is to include a basic and understandable tutorial in the documentation, or even in the TDN recourses.

#51 AI is more of a logic thing that is specific to the type of game that you are creating. For example, AI in a platformer is going to be completely different to the AI in a puzzle game. I think that you're better off googling AI programming and investing some time in developing the logic.

#52 The tutorial part is interesting but should perhaps be written differently. There are too much new principles introduced at once and by creating a new game each time, some points are repeated in about all the tutorials.
The tutorials should really focus on a specific point. A good idea is that the sum of all tutorials makes one really complete game (with GUI, menus, option screens, ...).

The reference part needs urgently a complete overhaul...this is just an almost list of all the available commands and objects. To start with, the newcomers really need a real complete description of what the command does, with examples of usage, with a complete description of all the parameters.

#53 I think what is implied by being a real Wiki is that it's more a less a dumping ground with no real checking, fact clean up unlike most of better maintained Wiki's out there. Regardless if it is powered by a Wiki Engine doesn't mean that it is indeed a Wiki.

#54 I suppose Wikipedia isn't much of a real wiki then since I usually end up fixing misinformation in the same way there as I would on TDN. There are checks in place [on Wikipedia], but they don't seem very effective in my experience.

Edit: []'s for clarification.

#55 David Blake: Wikipedia also has a team of editors enforcing cohesion, keeping things up-to-date, checking references, and culling junk. I would personally love to see TDN succeed, but it needs an active team of knowledgeable staff-backed contributing editors if it's going to succeed. I'm afraid that if it doesn't have that, it's doomed to suffer its life in a state of half-heartedness that will be as distracting as it is unreliable.

We need an easy channel for the community to give back -- static documentation that can only be contributed to by e-mailing GG staff is a *bad idea*. I think that moving the official documentation to TDN would be a *fantastic* way to go (all resources, reference, and tutorials).

But if we can't have that, a fast-feedback / comment system on the new documentation system will be appreciated too. :)

--clint

#56 I realize that, but I still see huge amounts of misinformation that are opted in on wikipedia. Which still makes it a bit of a sketchy source. More than a bit, actually. There's a lot of good information, but there's an awful lot of misinformation as well. Part of the problem is the speed of talkbacks, edits, and reporting as well as the openness of the wiki itself. There will always be very dark spots in an otherwise clean wiki, and wikipedia is no exception. And I attempt to fix any misinformation that I find. I assume that many others do the same. The problem comes when people use it as a defacto reference and redisseminate misinformation. It's a common problem in academia and intellectual writing and has been with us for as long as we've been writing and others haven't been checking our sources. But it is bigger and faster now.

#57 I guess then it's really about making sure that the information on TDN is correct and as accurate as possible.
Here is my idea to fix the TDN Issue.
Have two areas, Official Documentation and another area that Users can post Tips/Tricks/Tutorials.
The Official Documentation being controlled by Garage Games and the other area that can be edited by users.
If the users find an issue in the Official Documentation, they can report that issue and it would need to be fixed by those at Garage Games. As for controlling the quality of documentation in the Users portion, each topic can be voted on a Star/Point rating of 1 - 5, 1 Being Poor, 5 Being Great. You calculate out the results in an average. Each topic gets a 30 day time window, at the end of the 30 day window, one of the results below happen
A rating of 5: The post is extreamly good and will stay no questions asked.

A rating between 5 and 4: The post is well done but may need some slight modification, orginal author will be notified

A rating between 4 and 3: The post is ok but needs additional follow up, author will be notified

A rating between 3 and 2: The post is barely acceptable and needs heavy modifcation, will be removed 30 days if the author does not make a change on it

A rating between 2 and 1: The post is barely acceptable and needs heavy modifcation, will be removed 15 days if the author does not make a change on it

A rating of 1: The post is not acceptable and needs heavy modifcation, will be removed 5 days if the author does not make a change on it

Now once an author makes a change to the article, notifcation will be sent to those that voted on the article/post for a re-rating and the cycle happens over again. Now you could put a limit as to how many times an article is voted on, or what happens to if it receives a certain rating. If someone were to vote a certain way I would think that the author would like some feedback on what he needs to modify/add to the article to make it acceptable.

As for rewarding good articles, each person who submits an article that gets a good rating gets a certain number of points for that article. That could be used to determine who are the good authors and get special rewards for submitting good information.

I think that would be one good way to go with this.

#58 Extremely well-thought out suggestion. I quite like the thought of it, too.

#59 I think just having complete reference documents would help a lot of us (at least those who are into scripting and programming). Possibly some intended usage information should be included as well for some of the functions.

In addition to complete reference docs, I think that perhaps instead of tutorials (or possibly in addition to them), there could just be a content package (which includes scripts, sounds, art). A lot of those familiar with programming can gleam a lot more from real running code that you can run and play around with. I bought the Adventure Kit, and it was the single most useful purchase I've made aside from TGB itself. Just being able to run the game, see how awesome and complete it was, and then go in and actually look at how they do things was fantastic. There's not even that much documentation for it on TDN. Mostly just where to find some things, and the general layout of the kit. I think this is far more helpful than a step by step tutorial.

However, there are some using TGB who are not programmers, so I won't comment too much on what they might like. Yet, I do think that it's easier to modify something that's already existing, and try things out, instead of just starting with nothing.

#60 Hey guys, lots of good ideas in here. I wanted to add a few of my thoughts.

Quote:I somewhat agree with your idea of abolishing larger tutorials that may not promote people to run through them, wasting your time. If a long tutorial is made, it should be a base for other games, not something weird (fish game). I know it's difficult to think of things to do, but sometimes longer tutorials are needed.

On the otherhand, short tutorials aimed at fixing common issues are an excellent idea.

I think some people may have misinterpreted what Matt wrote in his original post, so I wanted to give my spin on things. When we say we're moving away from "full games" as the focus of our tutorials, that doesn't mean we're necessarily going down to just very short, low-level feature tutorials. We think that there are advantages in combining features and concepts together into a game (or at least a gamelike thing) in a fun and engaging way, which we think can make it easier to learn and remember the ideas that the tutorial covers.

The way we're thinking about things right now, is that when we write a tutorial we don't want to be necessarily tied into particular games as an end goal, i.e. "this is an RTS tutorial", "this is a scrolling shooter tutorial", etc. So, instead of "we want to teach people how to make game X, so we'll need to teach concepts A, B, and C", we want to think in terms of "we want to teach concepts D, E, and F, so how can we weave those together into something interesting? Well, we can do Y...". This is the philosophy behind the new Torque X tutorials that I wrote, if people want to see an example of what we think that means in practice. We think that there are a lot of advantages to thinking about it this way, such as being more likely that we'll cover a broader range of topics, rather than having multiple tutorials that all cover some of the same things and some topics that never get covered. It also helps the tutorials themselves to be less repetitive, since you can make eliminating boring stuff a priority while you're writing it, instead of genre conventions being the priority. There is a downside of this approach, though, in that the "end result" might not look exactly like a "game" (since the focus is much more on the journey of making the tutorial itself good rather than making sure you get to a "game" destination). For example, the Torque X Airplane Tutorial doesn't have any scoring, or even any actual interactions, it's mostly just moving your player around the screen, but it hopefully does that in a cool enough way that the tutorial is fun and engaging while you're doing it. This is probably going to turn some people off, since they really want to see "this is how you make a platformer" or "this is how you make an RTS" tutorials. We have some ideas about how address people who want that, but that's probably a longer term thing.