I7 : Well-Versed Guides

Hey all. In trying to get some wider acceptance for textual IF and Inform in particular (outside of the current community), I’ve been writing some “Well-Versed” guides. I have updated these to their most recent incarnation. They are located here:


The reason I bring these up now is because these latest incarnations actually worked in getting Inform 7 accepted as part of some teaching curricula. I’m happy to have anyone look at those and critique them. They are not finished documents yet but they certainly should be useful and accurate and thus are certainly open to comments, questions, suggestions, etc.

I’m particularly interested in whether people find the documents hard to follow. I’m worried they are a bit “choppy” and I’d like to provide the basis for that worry, just so everyone has the context. One of the big challenges with these guides – I’ve come to find – is that I’m essentially attempting to rewrite sections of Writing with Inform and trying to standardize on vocabulary or use terms consistently where the manuals do not. And since I’m never sure to what extent the official manual is going to change, I can’t easily reference it in my guides. But that also means I can’t “count on it” either. So I have to cover a lot of stuff that the official manuals may already provide.

The reason I’m taking this approach is that the official manual set that comes with Inform is, among my classes, universally disliked. That’s the one constant I’ve been able to deal with. Whether people in the textual IF community feel this is right or wrong, it’s the viewpoint of quite literally every single class I’ve given and the focal comment to quite literally every single attempt I’ve made to get Inform introduced as part of an actual curricula (for writing workshops). It essentially boils down to “We might give Inform a try, but the manual is going to have to be rewritten.” So I’ve been in this weird position where I mentally try to “forget” what the official manuals say and just go down my own path – but with the realization that every member of the class will have those manuals and can reference them. So it’s been necessary for me to sync up the knowledge I present with the knowledge in the manuals, not least of which is because I have to make sure I know what the heck I’m talking about.

All of this is to say that I think this has led to a bit of choppy writing on my part, where in some cases I think I do successfully “forget” what I know and write accordingly, but where in other cases I am implicitly assuming knowledge from the official manuals, and writing accordingly. That’s why I settled on the “Guide” format, where there can be guides of differing levels of detail. Some guides may be very mono-focused while others may be very broad in nature. The goal has always been to make the guides relatively easy to update pending changes in Inform 7 itself.

What I also want to do are a few of what I’m calling “Dissection Guides.” These are going to be guides that take certain relatively complicated examples (probably from the official manuals) and use them as the basis for a full tutorial that essentially recreates that example. Another aspect of this is taking existing extensions and essentially “rebuilding” the logic as part of the tutorial. This is sort of where the Locale guide is going. I’m going to present, for example, Room Description Control. Then go through a series of logic that essentially “rebuilds” one of the already existing extensions that relies on Room Description Control. So in the end the reader can just use the extension if they want – but now they have knowledge to not only tweak the existing extension if need be but also write their own.

Personally I find them invaluable… I like the detailed approach. I like the fact that you go through the code line by line, explaining each one. This is how I need to learn a programming language, I need to be sure of every single word and expression. I need it to be totally clear that this word is a variable, this one is built-in, this one you don’t really need, it’s just there for intelligibility, etc etc. (this is where some syntax colouring in I7 would help…). With the natural language “style” of Inform 7 you can sometimes forget that every word has to be right, the structure has to be programatically correct and logical. These are things I think the official manual brushes over at times.

So I welcome the detail, and I don’t mind at all that there is a kind of “customised” vocabulary. Eg when you talk about either/or properties as “behavior properties” - this is not maybe what I would have come up with or how the manual talks about them, but it’s clear what you mean and it’s good to have a typology laid out that you can work with.

Also, it fills a gap I find in Inform 7, which is a debugger - not from the point of view of catching errors, but of being able to see what is happening with every little thing in your code as it runs. A “watch variable” kind of tool, that lets you learn by observing the programme in action, changing part of it, now how does it run, what happens if I tweak this bit here… your examples are almost like that, they take a piece of code and are like “run this, OK, now change that line, see what happens.” The examples in the manual by contrast seem like a fait accompli, something you have to puzzle out (which can also be useful as a way of learning).

Anyway, I’m glad you’re continuing with it and I look forward to more!

Truly outstanding work!

Great work! Keep doing it. :stuck_out_tongue:

I really like the guides, and I think I have the latest versions downloaded. One question, though - since the directory you linked to appears to be empty now, where can the latest versions of the documents be found?

hi, would you be able to send me a copy of the guides? I was reading them in a browser window instead of downloading them (doh) and now they’ve gone…


I’d love to see these, too. I’m a programmer by trade and the Inform manuals, while beautifully written, are amazingly difficult to use as reference material when trying to find solutions to things (especially non-recipe book kinds of things) and are enough to drive me to drink. Would you be willing to repost your work?

There’s a manual targeted at programmers specifically:

The link is dead. :frowning: Where can I get the guides?