Oh cool, if you’re looking for perspectives on it, I gave your guide a second look and I think I bounced out of it too quickly the last time. I should have stuck through. The problem for me is that the version I read opened by using a lot of computer science terms to situate i7 within the larger family of programming languages, and it didn’t feel like what I wanted. What I needed at the time was as bare bones a spec as possible, I wanted an arrow into the heart of the language. Whereas your guide felt to me at the time like it just exchanged the official manual’s excess literary verbiage for a bunch of excess computer science philosophy verbiage. It seemed like it was going to be a different but not a faster way in.
I’ve taken another look since then, and it does get leaner later. It was just the way it opened up that scared me off because I felt like the goal of it was not directly to solve the official manual’s sometimes-maddening lack of to-the-pointness, but rather to communicate to people who are formally schooled in computer science, which I am not. I don’t know if that accurately describes what you were after, but taking that impression from the initial chapters is what put me off using it.
Yes, it is specifically aimed at those with a Comp Sci background, and not necessarily with an I-F background. I do assume they’ve at least played one I-F and so know the shape of the thing. So yes, the introductory nutshell chapter situates it just as you say. Despite all its terminology it’s probably the vaguest of the chapters. Take the term Object-Oriented, for example. While even many of the dabbler-programmers here know what that basically means, if you look at several OO languages, each’s notion of exactly what an object is and can do never matches up perfectly. Still, when a language is described as OO, it still says something useful. The other terms are similarly vague-but-not-meaningless.
I had other responses like yours: say it fast and straight. So in this current revision I added an extra chapter, the Firehose, which takes a whirlwind tour of the language before each of the following chapters digs into details. I’ve also had good feedback about taking a long example of a rule (esp. its preamble) and breaking it down word-by-word. I imagine because that’s one of the most unique parts of Inform, and a rule can read so well the programmer-ly mind doesn’t have anything to latch onto.
I’ll add a disclaimer in the opening of chapter 1 to the effect of, “you can skip this part.” I imagine that’ll save time for much of the audience.
Those sound like good revisions, especially the ‘Firehose’ thing. Yeah you can count me in with the ‘fast & straight’ crowd. I appreciate that there are some who will find the more deliberated, theoretical approach most useful because it fits their mental models, but self-taught programmers, if they’re anything like me, don’t really maintain more than a rough, rule-of-thumb mental model of language/compiler philosophies even when we are more than dabblers. We’re more about the shortest possible path to the code. There are a lot of parallels to music here, I keep thinking. Some don’t know chord theory but read sheet music; some don’t even read sheet music; all are musicians. 8)
Truly. I guess once you get the general theory of programming under your belt, you don’t want your hand held too much. I’m much more apt to learn from a plain-old reference sheet than a “guide” that teaches concepts with which you are familiar.
Ron, I’ve downloaded your eBook, and have gone through it a bit, but I haven’t had much time to really sink my teeth into it. I will keep in mind to give you any feedback if and when I come up with anything.
theraje,
good luck with the project. I’m using Inform7 for a first IF project and given my slightly out of date programming skills (Delphi, C++, etc) I think Inform7 is great, but it is not perfect. In particular, the lack of a good reference manual makes some things difficult to learn. But despite that, it has a lot of built-in functionality that is pretty amazing. I have not had to make any code changes as I7 has been updated, though I did have to get updates to some extensions (e.g. libraries.)
I have found Aaron Reed’s book to be a great resource and highly recommend it.
I guess once you get the general theory of programming under your belt, you don’t want your hand held too much. I’m much more apt to learn from a plain-old reference sheet than a “guide” that teaches concepts with which you are familiar.