intfiction.org

Time to get excited!

http://tads.org/ov_tads31.htm

Fantastic! Some of the new features are high-end stuff that I'm not likely ever to use, but there are some enhancements that (if I were writing a game) I'd use every day, including one that's obviously borrowed from a certain other popular IF authoring system. Very handy indeed.

The web server features look extremely muscular, but as I'm not really a programmer, I'm not sure yet what to make of them.

Congrats to MJR and the team!!!

Yeah!
The new Layout looks great!
The new features look awesome!
Thanks to all the people who contributed!

Greetings,
-- MI

This is great stuff. I'm finally going to give TADS more than a passing glance.

That brings me to an observation, not necessarily related to this version.

I decided to start going through the users guides. And I can maybe see why TADS wouldn't appeal to new people. I was reading (local reference of installed docs): file:///C:/TADS3/doc/gsg/creatingyourfirsttads3project.htm.

This is a really convoluted intro to new people getting started with TADS 3. I could easily see this turning off newbies or people with little experience setting up tools. It mentions too many specifics (like "If you're using Windows NT, 2000, or XP...") that shouldn't be there; if someone is adding to their environment PATH, they know this stuff. For those that don't want to, this is just noise that makes things seem complicated. There's also: "If you're on Unix, for example, you'd type mkdir obj." Well, yeah, it would be the same on Windows as well. (It feels like this one page was written by two entirely different people.)

Also mention is cumbersomely made of the "DOS command prompt on Windows" -- but if you have someone running TADS like this, you can probably just say "at the command line" since anyone embarking on that approach will already understand this concept. Talking about "DOS command prompt" and "Windows", again, just seems to throw a lot at someone who may just be getting started. There's also too much reference to TADS 2, even on just this one page. Someone coming at this new, won't even have that background and may wonder if they should, based on what they read. (Put TADS 2 specific notes as a footnote or something.)

More importantly, on the Web version of the guide, under "ii) Creating a project manually", it shows an example but that example doesn't show

#include <adv3.h>

while a latter mini-example on that same page does. That's not the case in the PDF, however. The PDF example does have the missing line. So, now, as a user I don't know which guide -- of this same exact document -- I can trust. Then a "project file" is explained (sort of) and it seems a little obtuse unless you know about build and/or make files. Right away I can just see this turning off people new to the system. And this is just in the first section of the first manual -- and a "Getting Started" one at that.

I'm not moaning about the author of the work since I appreciate when anyone takes time to document. Again I'm just stating the observation that if there's a desire to get people involved in TADS, having documentation proofread might help quite a bit. If I didn't have my background context, I probably would have given up already and just gone to Inform 7 which seems a lot easier to get right out of the box.

Here's another example from the same page:

"We promised earlier that we'd provide an explanation of the gibberish in the .t3m file. You should be able to get quite far sticking to the recipes above, so feel free to skip this section if you don't feel you need the details right now."

So it's "gibberish"? That's encouraging to a new user. But beyond that: "feel free to skip this section if you don't feel you need the details right now." Okay -- but how do I know? As a new person, I don't know what I don't know. I don't know the things I need and don't need. And given that I already have trust issues with the document, now I'm even more uncertain.

And here's another example where PDF and Web differ. The PDF includes this line:

-D LANGUAGE=en_us

The Web version does not.

Again, I understand: you may not need this. It may be handled for you. It may just be "gibberish." But it took me no time at all to find these discrepancies. Everyone's frustration factor is different but it seems text adventure development has a wide range of users with very differing levels of experience in terms of using tools like these.

Sorry -- at this point, I'm derailing the thread. But given that TADS 3.1 seems to offer lots of new features and a cool long-awaited feature of Web deployment, it just seems like the right time to get new people involved -- but if this documentation is what they have to go on ....

I opened a bug report for those doc issues a few months ago and it was marked as fixed. It looks like some of the new documentation may not have gone live yet.

You're right, though. It's off-putting to newcomers; the report came about when someone else on this forum ran squarely into issues caused by omitting those lines.

As for the style issues, I agree that it seems like the document is trying to be accessible to both non-technical and technical folks, and falling somewhere in the middle. I found it quite helpful when getting started but I skimmed past the Windows stuff and really enjoyed the next section - Programming Prolegomena - which is marked as optional.

There's probably a space for new material targeting both types. Something like Learn TADS 3 The Hard Way for the one, and Aaron Reed's Inform 7 book for the other. I7 has a better out-of-box experience, no question, and to a large extent that enables more accessible tutorials. The writer can assume a standard platform for all readers and skip all the window dressing.

(EDIT: I've re-opened my ticket; the fix seems to have been lost in the shuffle.)

I hadn't looked at that page in a long, long time, and I agree with you. I suspect Eric wrote that material quite early in the development of T3, and it does need to be revised in light of (a) how most people will be learning T3 today and (b) the more robust competition from I7.

If I were writing it today, I'd make the top-level distinction, "Are you using Windows or not?" Because if you are, you can just install the whole Author's Kit and then launch Workbench. You never need to touch that other stuff. The other stuff is relevant only for Mac and Linux users.

It's like Christmas in December! Seriously though, this is great news.

Systems that have been around a long time like TADS 3 always need some nip and tuck in their docs.

One thing that I think could help, which you don't tend to see with IF systems compared to other programming languages for whatever reason, is the "getting started with <X>" kind of blog post. I wouldn't be surprised if there were literally millions of these posts floating around for languages like Python, Ruby, JavaScript, etcetera.

The two key characteristics of those posts is that they're short and aimed at the absolute beginner. As such almost anyone, including a TADS beginner, can write them. They've always been a big help to me getting started with a new thing.

edit to add: Just downloaded 3.1, and the user experience was really good, nice work!

That's absolutely right. In terms of the life-span of T3 that part of the documentation is quite antediluvian. So far as I recall, it's not even something I wrote myself; I think I just incorporated some of Mike's older documentation at that point for the purposes of the first official release.



I agree it probably does need revising. In fact I've felt some discontent with Getting Started for a while, which is one reason I wrote Learning TADS 3 as an alternative. Quite a while back I posted on the old TADS 3 list suggesting a thorough re-write of the Getting Started guide might be needed, but at the time the suggestion was met with a distinct lack of enthusiasm. Since then I've not had the time or energy to pursue it.



That might be a useful approach. I think the prior question is, how can creating a new game in TADS 3 be made as easy as possible for non-Windows users (especially non-Windows beginners)? As a Windows user with no experience of Mac or Unix (apart from briefly using Xenix at work in the early 90s) I'm not familiar enough with non-Windows flavours of TADS 3 to know. It's a good idea to make it clear to Windows users that they should just use Workbench and ignore the rest (at least, for introductory purposes) but I'd need input from non-Windows users on how best to present the material for them. Or would it be better to take the manual creation of a new game file out of Getting Started altogether, and stick in in the Technical Manual?

OS X and Linux development is essentially just FrobTADS + a text editor + a terminal.

I'm quite happy with my setup now but I remember looking for a long time for an editor with decent syntax highlighting for TADS. Eventually I settled on gVim / MacVim. That's not a choice that will work for everyone and it's somewhat cruel as a recommendation for beginners, but it works really well as a T3 dev environment.

General best practice recommendations:

- Name your makefile 'Makefile.t3m'. One of the guides had me do something else and I had to supply a filename to t3make every time I recompiled. Nikos eventually enlightened me and that was a big quality of life boost. Now I can map <F5> to save & invoke the compiler and it works no matter what project I'm editing.

- Make a project specific header file first. Put the includes for adv3 and en_us in there. Then include only that header at the top of all your other source files. This makes it a lot easier to define macros and templates and libGlobal aliases down the road.

- Have some sort of version-controlled store. Dropbox works pretty well at first; put your project files in a folder there and you're set. That lets you recover an earlier version of a file from up to 30 days in the past. Eventually I moved to Fossil for source control.

One thing that might help would be a skeleton option that you could pass to t3make to get it to create a new project in a particular directory. Run "t3make -skel <dir>" and it creates a Makefile.t3m, <dirname>.t, <dirname>.h, and an obj/ subdirectory.

Authors could eventually customize that skeletal structure to taste but the defaults would be sensible and allow for a step-by-step guide without a lot of decision points.