Beta Documentation Feedback

#1 FIRST PUSH IS LIVE: Official Torque 3D Documentation

This is about half of the World Editor docs. The other half will be posted tomorrow. This is mainly a test. Make sure you follow the doc instructions carefully. I point out where you should start reading.

Do not worry about missing links just yet, as there is a ton of content being pushed tomorrow.

#2 BUG: Found a confusing typo.

".dso - This is a TorqueScript file that has been compiled into an encrypted format. TSO files are more secure, and must be compiled before you can test your game on an iPhone or simulator."

Are compiled .ts files .dso or .tso files now?

EDIT: Found under File Descriptions, in the Beginning Guide -> Getting Started section

#3 Good catch. That is an error. At the time of writing we were thinking about renaming the .cs extension to .ts, to separate our stuff from C#.

So if we have .ts, you would get .tso. I'll change it back for the beta, since we have not decided to make that change.

#4 Ha, good find. To me I just read it as "TSO files are more secure," as if it were a more secure version of DSO. Also, at the end of the Precipitation page, is a link to "Replicators," which does not show up under the Table of Contents.

#5 @Neill - Yeah, that's one of the files I did not push live. The other half of the world editor docs are being pushed all during the day tomorrow.

#6 Seems to be a missing page. I clicked ground cover in the beginner guide. Same for particleemitternode and mission objects.

Not Found

The requested URL /t3d/official/content/documentation/Beginner Guide/World Editor/GroundCover.html was not found on this server.

#7 Pretty thorough docs so far, nice job.

#8 @Neill and Timothy - As stated at the top of this thread in the OP:

Known Issues

- Tooltips scripts are not working (javascript)
- Component tutorials are not working (javascript)
- Half of the world editor docs are not uploaded yet

#9 Very nice work.
Have not spotted anything to report so far so I guess if there is something then it will show up when putting the docs in relation to the "real world", at least for the part already present

#10 Typos:
(minor) Introduction->Using The Docs->Reading Order: paragraph 2/sentence 1
"If you create models, 2D images, and other assets, +you+ should obviously read through the Artist Section."

Optional Suggestions:
Beginner Guide->Getting Started->Directory Overview->Torque 3D Project Tour:
So as not to confuse absolute beginners, change the directory from 'FPS Genre Kit' to something like 'My First Project' in the images, to show that this is for any generated project.

In order to reduce a bloated thread, I'll try to condense my findings and post after reading a few sections at a time. :)

edit: not saying there are a lot of mistakes, lol

#11 @Marc - That's a good point. After I pushed these live, I told Tech & Tools. I've already gotten feedback from some of the developers on what has changed in the past two days. For instance, three of the fields in WaterBlock are no longer present.

This, my friends, is the definition of "aiming at a moving target." By the time I finish an article, there is a chance it is already outdated. It's either deal with that stress, or not write docs until the engine is finished...which means no documentation when the engine ships. That...is definitely unacceptable for Torque 3D.

#12 Is it possible to have the page in the main window hi-lighted in the left Table of Contents? This would help, especially seeing that the page in the main window doesn't have a title and always seems to start with the Contents block.


Also in the File Descriptions part of the Directory Overview you have this:

dll - Dynamically Linked Library files (DLL) contain code that can be used during runtime, instead of being compiled directly into *TGB*

( or should we not worry about minor typos like this at this stage? )

#13 BUG:
missing image file (Image azimuth.png) on the sun tutorial page

#14 @Gerry - Please post anything you see at all. Even typos

@Kenneth - Thanks. saw that.

#15 Each gizmo has a unique appearance to notify you of what you are adjust.
Grammar/typo - adjusting

edit:
1. Notice how the new shape is already list and casting a dynamic shadow. - listed
2. Adding a COLLADA shape as just as easy as adding DTS shapes. - is
Typos

#16 I don't worry about a 100% up to date doc state. As long as it does not state actively incorrect things that remove more use than it offers.

A potential error that I remembered due to your above posting:
The folder structure article has an Atlas folder in the sources directory.
I assume that one is no longer present in T3D and dates back to TGEA?

#17 @Michael - This is easily the best written material I have ever seen for a Torque technology yet. I can't imagine how difficult and frustrating it is to write documentation for a 'moving target'. And since this is a feedback thread I thought I show my immense appreciation for your efforts so far and to keep up the good work ;)

P.S. This is really awesome stuff so far.

#18 @Mich, sorry to derail a bit, but did you consider on this write-from-scratch some way of putting all-in-one format for easy printing?

#19 Bug
Again with the TOC:
Expand ( click on + sign ) Beginner Guide
then expand Getting Started
then click on Directory View
it will expand the World Editor section
and the ParticleEmitterNode section under that.

Superfluous or Outdated text
The last line of Using The Docs in the Introduction:
it says (TODO: Link to Beginner Guide) after the sentence that already has a link to that page in it.

Typo
First sentence of second paragraph on the very first page missing an article:
The official documentation is divided into multiple sections, each of which contains information related to +a+ specific subject.

#20 @Mich a second post, this time more on-topic.

Your current scheme jumps fast into the Editors. Are you considering writing down some hints about a recommended compilation environment?

I mean, the previous official docs made that point clear to ridiculous points, like explaining how to check the video driver version, screenshot by screenshot (no offense), but now there is nothing at all! =)

Im probably rushing, but Im anxious to know, sorry :)