What is required?

What should be the format? (ie Java Documentation model, a PHP/MYSQL solution, a wiki how-to page

Should it be developed in multiple formats? ie Conext Highlighter, html, XML, others?

How would it be controlled to keep it on target and focused (I vote a few indians (like me, we do the grunt work), some advisors (Sing, Prom, LS, Mind Dagger and others to check the grunt work) and 1 chief (EP, has the final say)

How do we break it down into pieces to make the work easier on the indians and the advisors?

Do we need a script example for every command?

How do we make it easy enough to read for the n00b scripter and comprensive and detailed enough to help the experiences scripter?

Do we need a n00b version, intermediate version and an advanced version. (each version covering the same information but each one more detailed and comprensive the previous version)

----
As you can see I have far more questions than answers. If there is going to be a 'TWX Documentation Project' what can we do to make it 1. Worth the work we will put into it, 2. Useful to players, 3. Keep it from turning into either vaporware or so full of conflict it doesnt get finished.

Help!

Helix

I think you definitely need a multi-level approach to address new scripters that have never even seen an "if/end" decision or what a variable even is. As much as we like to try to run before walking, it is good to have the very basic information. There are three documents currently out that I believe are out, one that I did and two that Traitor did. Traitor also has a very nice "stupid ansi tricks" that is a good read.

Examples of every command may not be needed or it could be a very simple example. Depends on the command.

               / Promethius / Enigma / Wolfen /

"A man who has no skills can be taught, a man who has no honor has nothing."

Can you post a link to the document you created?

Right from TWX v2.04 Help
TWX v2.04 Scripting Guide
TWX v2.04 Pack2 Scripting Guide

Traitor's Stuff
TWX Scripting Help - Part 1 and Part 2
Stupid ANSI Tricks

Prom's Stuff
TWXScripting.doc

XIDE's Stuff - http://www.twxproxy.com
by XIDE
Warrior's Guide to TWXProxy, Part 1 - Getting Started
Warrior's Guide to TWXProxy, Part 2 - Burst
Warrior's Guide to TWXProxy, Part 3 - The Database

TWX Scripting Guide, Part 1 - Basic Scripting
TWX Scripting Guide, Part 2 - Flexible Scripts
TWX Scripting Guide, Part 3 - Trigger Theory

by Blackice
Basic Arrays

I actually first learned TWX scripting from some of Traitor's very-well documented scripts. I learn from real-world examples, applied scripting if you will. One solutions would be to have a target purpose, then show a novice way to accomplish, followed by an intermediate way, and finally an advanced way. But each example should be well documented, which will be easier and cleaner with inline comments, which are about to be introduced. I personally don't find well documented code easy to read as it currently stands, because 3 or 4 lines of comments interrupts the flow of code.

I think that Xide was onto something with his online script reference. I would like to see this expanded with lots of script examples.

On the programming side, I think that the TWXIDE project that I started is a very good utility for new or experienced scripters. I would like to see it extended to have a more thorough language reference, and a snippet library. Eventually, I would like to see it incorporate intellisense type code completion, and maybe even output directly to the compiler. You can find the source by googling twxide.

Why don't we just do a wiki?

Each command can have a wiki page, and examples can be tacked on to each page as ppl do them. If people feel like uploading summary scripts that would demonstrate multiple commands then hybrid categories can be created for that purpose.

The link is: viewtopic.php?f=15&t=21677

The doc is embedded in the post.

               / Promethius / Enigma / Wolfen /

"A man who has no skills can be taught, a man who has no honor has nothing."

Why not? Can the page for each command be locked down after EP's final say of go/no go? Can the wiki handle multiple versions of each command? (beginning, intermediate, advanced)

Helix

Edit: BTW, LS, you have those 2 script tutorials, can you post links to them?

Pages can be locked, but there's not much point to it. It's basically a versioning system, and people can add whatever they want and make a new version. If the version isn't good it can be regressed back, allowing for us to modify as needed while keeping quality high. Ppl can be appointed as moderators if necessary. That allows for continual peer review, well into the future.

As for multiple versions, why? Why not do a basic version, then just link from the basic version to advanced examples on an "advanced example" page? That way we don't have to make separate versions (time consuming) but we can still keep the more advanced examples from confusing people before their time. I'm not sure an "intermediate" is needed since everyone's opinion of what "intermediate" is will differ, but it's pretty easy to distinguish between "basic" and "advanced" examples.

Before we commit tho I'll put up a mediawiki on navhaz and give it a go. We can test out the concept before deciding.

One of the other questions is... can we make it portable.

But I will say the reasons for having multiple versions is simple. How many commands are available in TWX? (I dont know) How many of those commands matter to a beginner? (about 20 according to EP)

Also we still haven't define the point of this. We need a clear cut goal. Without one, we are spinning our gears.

Do we want to create a piece of documentation, portable or not, that defines what twx is capable of doing and how to do it?

Do we want to create a list of commands that people can look through for the info they need? (we have that already, we just need to expand on it)

Do we want to work by what it takes to complete a task in TWX? (Moving, Porting, Attacking....)

Do we want to create a series of tutorials?

A house doesn't get built by choosing the tools first. First the plans are laid, the material is gathered, then you pick the tools you need to get it done. You need framers, plumbers, electricians, and inspectors. The point being that the house gets built because all the different people are working from the same set of plans.

Helix

It can be made into a series of HTML docs, but a wiki is a living document, not a static compilation.



You can make a page "commands a beginner needs" and put a tutorial there that talks about them, links to those individual commands, etc. This isn't a static document, it's dozens of individual pages that cross-link to one another. Each page is small, to the point, and absolutely on-topic. Instead of expanding a page to cover additional topics, new pages are created and linked from the relevant related sections.

The reason for that is simple: effort. Nobody is ever going to sit down and write an in-depth command reference. Tutorials are about as far as that'll ever get.

Those w/ the knowledge don't have the time. Breaking the problem down into a series of smaller pages will allow people to make the most of the time they want to invest while making the problem digestible.



People have talked about it since 2004. It hasn't happened. I'm going to speculate that at the current rate, a comprehensive (which is a definition no one will ever agree upon) single "piece of documentation" is not going to happen. You'd need 1 person to basically sit down and write it up, and that's just too time consuming.



That already exists. When the SVN comes up, you can expand the script.html just as you would other file versions and people can add to it as they see fit. But the script.html is just a flat document, and you're going to end up with version wars.



I don't think people will ever agree to a single goal. So why not make it flexible? The point of a living page is that people can have differing opinions and submit their version of a page with their personal goals in mind. If others like it, they can link to it.

actually I have those. plus two more with dust on them (Arrays & Genesis Of Macro to Script). and my own personal Routine-Library that I use to whip scripts together P.D.Q. I'll update my web site later today.

I think it would be beneficial to include routines on Logic, Programming Concepts, and Data Management. things I've been keeping on the backburner for future 'tutorials'.

So lets keep it simple. What are the 20 commands a n00b needs to script in TWX? Lets start with that list. If what you say is true. the doc will grow off those 20 commands. (in whatever form.)

Helix

Lonestar, were you planning to make your routine library available on your site when you update it? Sounds like something very handy to have and I would like a copy if you are going to make it available. Pretty please? Hehe