Making TADS Approachable

This is not a complaint post. This is an observation post. I don’t do much with interactive fiction these days but I do a lot of framework and library design in the software IT world, creating fluent interfaces and whatnot. So I do have some basis for why I’m bringing this up, even if the context is entirely different.

My concern: TADS is becoming less approachable and less friendly to newcomers.

Here’s what I understand about how TADS libraries are shaping up:

  1. You have the regular, out-of-the-box Adv3 library that has a lot of complexity but is modular so that complexity can be made manageable.
  2. You now have the Adv3Lite library. Not really a “lite” version in the traditional sense; rather a library that is even more modular than Adv3 with some refined functionality, largely taking its cues from Inform 7 but with a TADS 3 twist.
  3. You have an Adv3Liter library. Since Adv3Lite is not really “lite”, this is not really “liter”, but is rather just a more lean version of Adv3Lite. (This one is described as the “true lite” version.)

What I’m finding is that when you try to present this to people who are new to TADS 3 entirely, this is actually fairly daunting to them.

Whereas before you had one library that may have been complex depending on how you chose to use it, now you have three libraries.

  • One that that is the “true lite” (called Adv3Liter).
  • One that is “lite-but-not-really-lite” (called Adv3Lite).
  • One that is presumably “full featured” even though the others are “full featured” (called Adv3).

Further, the libraries are not entirely compatible. Adv3Liter/Adv3Lite are not strictly compatible with Adv3 and have different ways of stating key constructs (like vocabWords). So sometimes you have to learn things, other times you have to unlearn things.

It seems to me like Adv3 simply should be have been refactored (mind, not redesigned!) as “Adv3Lite”. It was already a modular library; it was just – arguably – presenting too much of its complexity up front. So streamline the interface, and thus the presentation of the library, and put the focus on the modular aspects for those who want to dig deeper. I have to believe, but don’t know for sure yet, that Adv3 could have been further refactored to accommodate the Inform 7-like constructs that Adv3Lite provides.

It’s stated that the “Mercury parser [with Adv3Lite] is a bit easier to customize than the parser that comes with adv3.” What this tells me is a “harder to customize” parser is left in place (as Adv3) but an easier to customize one is available (Adv3Lite). So why not just make the “harder to customize” one “easier to customize”? Then you don’t have to add more libraries; you refactor and refine your existing one.

I realize that ship has sailed and may not have been any of our decision or even open for debate, but my concern remains: I think TADS 3 has actually become much less approachable.

Obviously a lot of this is subjective, so I’m curious what others think.

Three points:

(1) adv3/TADS 3 is the work of Mike Roberts. Adv3Lite is my project (which Mike knows about and seems happy for me to pursue). Mike proposed a simpler Mercury library but never got all that far with it. Discussion of what should have been done is a bit academic when no one is in charge of both projects.

(2) If adv3 had been refactored as adv3Lite, any existing legacy adv3 code wouldn’t suddenly cease to exist, and people would still have copies of the adv3 library, so there’d still be two libraries out there, the original adv3 and the new adv3Lite. The older one would still need to be supported, at least for a while, for the sake of people who had started writing games with it (unless the new version were fully backwards-compatible with the old one, which would rather restrict the extent to which adv3 could be refactored as adv3Lite).

(3) Alternative libraries to IF authoring system aren’t exactly a novelty. There was the WorldClass library for TADS 2 IIRC and at least one alternative library for Inform 6 (whose name temporarily escapes me). I don’t recall these creating lots of confusion or creating barriers to the use of TADS 2 or Inform 6.

[EDIT: This was in response to your original post, which I do want to make sure I address even though I realize you changed it a bit.]

I’m truly sorry you feel that way. This was in no way intended as a personal attack against your work. As I said, I’m an open source developer (github.com/jnyman). I release software that is used not just a large segment of the testing community but also by companies as large as Oracle and, believe me, I get critiques all the time. And I actually prefer that as it means people are engaging with and thinking about what I provide. People who agree with everything I do usually are not helping me as much as those who do not.

Side note: In fact, I just did a blog series on my Dialect project where I fully admitted that my original framework, called Fluent, was pretty much utter crap. So I definitely eat my own dog food, in that sense. (testerstories.com/category/dialect/, if curious.) I’m not saying Adv3Lite is anything like that and I’m certainly not saying it’s “utter crap”; I’m simply saying that when you put yourself out there, it doesn’t hurt to look objectively at what you are putting out there.

Nothing I said in my post denied that a lot of work was done nor did anything I said suggest that aspects of the work itself was somehow wrong. In fact, it’s quite the opposite: it feels like Adv3Lite is probably what Adv3 should have been to begin with. Easy to say in hindsight, of course. As developers, we all know the lens of the future is not available to us. So my argument is largely saying that it’s at least possible that Adv3 should have been refactored which may – and note, I say may – reduce the possibly complexity, of perception thereof, of having even more components to TADS (in the sense of alternative libraries).

If TADS is already perceived as complex, then, yes, adding more choice to it can add to the complexity. (Can; not necessarily will.) There is a reason why convention over configuration is considered a very good design practice. (Witness Rails. Witness Maven. To a certain extent, witness even Inform 7.)

Keep in mind that what I was doing was simply posting some observations based on someone who has used TADS in the past, is coming back to it after a long hiatus, but who is also involved in teaching interactive fiction to others and thus tries to look at these systems through the eyes of those others.

Expecting newcomers to make an informed decision about whether to use adv3 or adv3Lite would indeed be daunting. But then, expecting newcomers to make an informed decision about whether to use Inform 6 or Inform 7 would also be daunting. Most newcomers seem simply to tumble down the rabbit hole into Inform 7 without considering the alternatives or attempting to make an informed decision.

On that basis, I would suggest that your concerns are misplaced.

If you want to help newcomers avoid the necessity of informing themselves about the details of adv3 and adv3Lite before starting to write a game, I can give you a simple answer, on the basis that I’ve used both:

Choose adv3Lite.

Eric’s observation that adv3 would continue to exist even if adv3Lite were made the official T3 library is on point. Newcomers would still be presented with a choice.

I would add that when you say, “I think TADS 3 has actually become much less approachable,” you seem to be implying that T3 would have been more approachable than it is now if Eric had never created adv3Lite. This, it seems to me, is actually a bit silly. How can creating a more approachable library make a system less approachable?

As I implied in my previous reply, you don’t have to unlearn anything at all if you haven’t previously learned adv3. What you’re describing here is, with respect to new authors, a nonexistent problem. If you just pretend you never heard of adv3, the apparent problem goes away.

I’m not a software developer, so I may be wrong in what I’m about to say, but it strikes me that what you’re suggesting here would have been (a) even more work than creating adv3Lite, (b) at best, a complex wad of kludges, and © more daunting for the newcomer, rather than less.

The adv3 class structure is deep and broad. The adv3Lite class structure is simpler. Many items that are presented to the author as “classes” are actually instances of the Thing class that simply have a property set to true rather than nil. My suspicion (again, not being a developer) is that streamlining the adv3 class hierarchy so as to allow this type of functionality would have been difficult. I’m sure there are other aspects of the redesign that would have presented similar difficulties.

What Eric has done, it seems to me, is to combine the best features of adv3 and Inform 7. As an author who has used both systems extensively, he is uniquely qualified to undertake this. (Of course, the most recent version of adv3 also borrows I7’s ability to insert <> constructions in text. But adv3Lite goes quite a bit further.)

But there’s more to it than that. What Eric did was not just graft I7 features onto T3. He also simplified some other aspects of the process. Here’s a trivial example: In adv3, a check() block uses the failCheck() macro to stop the action. In adv3Lite, failCheck() is no longer needed – if the check() routine prints anything, the library concludes, very appropriately, that the action is to be stopped. I’m not necessarily aware of (or don’t recall) other ideas along these lines, but it does seem to me that overlaying that type of functionality into adv3 code would have been fraught with peril.

Also, for the record … if you’re offering guidance to new authors who are choosing an authoring system, you really ought to point out to them the notoriously sluggish manner in which Graham Nelson provides bug-fix updates to Inform 7 (or, rather, doesn’t). Eric is much more active as a developer. In my book, that is an important factor for new authors to consider. I studiously avoid kvetching about this in the Inform forum, but if we’re talking about advice to newcomers, it’s certainly something they would want to be aware of.

Not to pile on, but, well, let me pile on the experience of one of those people who were new to TADS 3 entirely and who had to evaluate whether to use adv3 or adv3Lite. I fully agree with the sentiment that, for the newcomer to the party, there should be no need to unlearn anything. There is, simply, TADS3. Using the most currently updated and actively supported library. That would be adv3Lite.

Old-timers such as yourself may have to undergo a bit of re-education, but…well, 'twas ever thus. The new supplants the old. There’s a bit of adjustment required. But there is no need to subject the double learning curve on the newcomers you are seeking to guide.

I started working with TADS when adv3Lite was in the late stages of beta. I knew nothing about TADS3, much less the two libraries and I needed to reach a decision quickly about which library to pursue.

When I jumped into the TADS pool, I spent just enough time with adv3 to know that it was going to be a fairly steep learning curve, and the promise of some relief through adv3Lite was persuasive.

With some 20 years as a technical writer documenting network management and network security systems, including writing c/c++/java API references and programming guides and developing sample applications, I have some experience evaluating software development tools. I chose Lite and have stuck with it exclusively, with no regrets.

What would have been daunting is to have to learn both in order to make an “informed” choice as to which I liked better.

If you truly want to assume the role of guru helping to ease the path for newcomers to IF and TADS, you should, IMHO, be making that informed decision for them and simply telling them that adv3Lite is the library to use. With all due respect to its long and lustrous CV, for newcomers, at least, adv3 should be left on the “of historical interest” shelf.

Jerry

People do realize the title of my thread was “Making TADS Approachable”, right? Not “Making Adv3 Approachable”?

If it’s cumbersome to use an ecosystem as a whole, it doesn’t really matter how approachable one aspect of it is.

Jim says:

Jerry says:

You both seem to be completely misreading what I said. Perhaps I didn’t say it well but I felt it was clear and unambiguous when I said: “it feels like Adv3Lite is probably what Adv3 should have been to begin with.” To head off any misreadings, I also stated that I realize that lens of foresight is not always available to us. What I am saying is that when you introduce choice, especially choice that you have to bolt on to the system (as you do with Adv3Lite), that can – not necessarily will – add some perceived complexity.

Now, all this may change if a new release of TADS 3 is going to incorporate Adv3Lite and, further, make it the default. Perhaps that’s the plan? If so, that would have been a great bit of info to have and that’s certainly how I would have responded. Right now, however, you can’t even get Adv3Lite displayed in the IDE until you download it from an entirely separate site, unzip it somewhere, open the IDE for the first time, make Adv3Lite available via a dialog box that you get to from a menu option, and then re-open the IDE.

So the issue I was bringing up, stated in a different way, is simply this: To make TADS more approachable, would it help to simply have one library?

That can lead into design questions about: Could Adv3Lite simply replace Adv3?

This can also aid future plans for further refinement of TADS and its library. For example, one lesson to be drawn is design to a contract. The other is program to an interface. Had those concepts been operative, I do think the refactor of Adv3 into Adv3Lite would have been much easier and would still have maintained a backward compatibility of sorts. As I said, that ship has sailed. So maybe thinking about it now wouldn’t hurt especially if, as Eric says, “discussion of what should have been done is a bit academic when no one is in charge of both projects.” So, learning the lesson from the past, now people can be discussing these things.

That’s really a decision only Mike Roberts could make. The rest of us have no control over what is or is not included with the standard TADS distribution. I fully take the point that it would be easier for potential adv3Lite users if adv3lite were installed as part of the standard TADS 3 installation, but this is something outside my control. Perhaps if enough people requested it Mike might consider it (I really have no idea), but it’s quite a while since I last heard from him.

Hindsight is always 20/20. Windows 7 is what Windows 3.1 should have been to begin with. :smiley:

Mike did a fantastic job creating a very complex library. Ten years later, it’s possible to see (as Eric did) that some features could be added and certain internal processes could be streamlined without significantly impacting what the author can do.

I agree that installing adv3Lite could be easier. And perhaps you’re right that it should be the default distro – that’s up to Mike. But a few extra installation steps are not quite the same thing as introducing choice.

But as Eric pointed out, adv3 would still need to be available, both for works-in-progress and for the benefit of people who might prefer it. So I don’t quite understand what you’re suggesting. I don’t see that what you’re suggesting is even possible, short of creating a chimaera that grafts adv3Lite into adv3 … and that would be yet a third library!

Indeed it can. It does. Aside from a few extra steps during installation.

I appreciate that you’re raising these questions, Jeff. I don’t want to be misread as attacking you. Your perspective on these topics is unique and valuable.

Possibly the installation can be streamlined, or adv3Lite made the default. Perhaps Mike will read this thread and get some ideas from it. Possibly a switch in Workbench that you click on when you’re starting a project, which not only affects what library files are linked to but also changes what the documentation button links to.

But I do have the impression that you’re coming from a rather idealistic place. Development in IF is such a very tiny field, idealism can all too easily be misread as grousing. If you’re concerned that installing adv3Lite is a bit awkward for your students, by all means, write a how-to document!

Perhaps the main reason Adv3Lite is not yet included in TADS installation by default is that it’s still very young and have much shorter release cycle than TADS itself. It would be impractical to have a year old Adv3Lite version bundled with TADS 3.1.3 which was released June 4, 2013. But in the future I believe it will make sense to distribute both libraries side by side.