What Is a Construction?

Authoring Inform 7
1

Tonight I happened to glance at page 21.1 of “Writing with Inform.” I found it utterly baffling. The very first sentence stopped me cold: “Most, if not quite all, Inform constructions are values - sometimes openly so, sometimes not.”

I found myself wondering, what does the word “construction” mean in that sentence? Is the description property of a room, for instance, a construction? I have no idea.

So I searched for the word “construction” in “Writing with Inform” using the search field. I was unable to find a definition of the term. It’s used a few times. Page 8.16, for instance, refers to “the ‘number of …’ construction.” But a scattered example or two hardly qualifies as an effective definition of something that is apparently a universal aspect of the language.

Page 21.1 asserts that constructions “are ways to make new kinds from existing ones.” This would probably be more informative if we knew what a construction is. We’re given a list of nine distinct constructions, but with no examples of any of the nine types, and no explanation of how any of them might be used.

Given that assertion, in what sense is the phrase “the number of edible things carried” (to quote 8.16) making a new kind from an existing one? How does a “K based rule producing L” make a new kind from an existing kind? And in what sense is a “K based rule producing L” a value, for Pete’s sake?

A little further down page 21.1, I stumbled onto this: “Nothing will make that a simple idea, but it’s unambiguous and can be puzzled out with practice.” Oh-kay. It’s not a simple idea. You’ll get no argument from me on that point. But am I out of line in thinking that the manual ought to sit down and patiently explain this non-simple idea to us, rather than just tossing us into the big tank with the piranha?

Every few months I start thinking, “I’d like to really master Inform 7. I know it’s sophisticated. I’d like to understand every detail of how it works.” And then I run into something like this, and I change my mind. I start thinking maybe I’ll play the piano instead.

–JA

2

I like to play musical instruments when I get frustrated. I’ve been on the guitar lately since I don’t live in a place with a piano, but I miss it.

3

It’s easy for me to understand how this happened, because the vocabulary and grammar of Inform 7 are like a many-headed hydra. I think what happened to you is essentially a form of vocab panic with which I’m well familiar now as an i7 learner. You were so used to stumbling across undefined terms in the manual that you began to lose the ability to differentiate between special programming terms and ordinary English terms used ordinarily. I constantly have this problem with the Inform manual, even though I’m pretty familiar with what is typically a programming concept and what is not, from prior knowledge.

A “construction” as used in the Inform manual is no different from in ordinary English. There is no special programming definition of “construction” nor as far as I can tell is there any Inform-specific usage for this term. When they say, ‘Here are nine constructions,’ what they mean is, ‘Here are nine examples of ways to phrase things.’ When your grammar teacher talks about constructions he or she just means any form of sentence construction, there is no special form that makes it a ‘construction’; that word covers everything. Unless I am also confused (which is possible) it seems to me that the term is used just as generally in the Inform manual as it is everywhere else. So, a ‘Rule’ is a construction. A ‘Phrase’ is a construction. Everything you type into Inform is a construction.

You can definitely be forgiven for thinking that they were introducing another technical term to the reader before defining it: because they do that a lot in the manual, and most of Inform’s technical terms resemble ordinary English terms, so that breeds its own class of confusion; namely, ‘Do you mean in the ordinary English sense or is this yet another voodoo sense for an ordinary word of which I am not yet aware? And if even you, the Inform manual writer, cannot put yourself in the mindset of very explicitly noting the differences, how do you expect me to?’

Basically, if you don’t already have a good sense of what is a programming concept and what is just a verbal concept, the manual isn’t really going to be too careful to differentiate them for you. Because that would read too much like a programming manual, always setting off terms as separate, and as having their own meaning independently of the English language? Did natural language evangelism get in the way of simply writing a clear spec? Or was there some other notion at work? I dunno the reasons, that’s just me speculating, but for whatever reason, the approach to the i7 manual is extremely different than in the manual for i6, which was very rigorous about defining its terms and wouldn’t think of portraying anything as deducible from English, because i6 is obviously not. Perhaps less obviously, Inform 7 isn’t deducible at all from English either, so I don’t know why the same exact rigour wasn’t adopted about not making extensive use of terms before they have been properly defined.

What a manual needs is to completely abandon the idea that Inform is anything like English and to just pretend it isn’t at all. IMO! (I’m sure I’m not the first to point this out. And I know others have even written their own manuals.) Just define every term upon arrival, with extreme prejudice — exactly as if these deceptively English-sounding terms have been handed down to us from Martians obsessed with human cable shows, but if we were to use them the way an English speaker would rather than the way a Martian does, we’d be risking an alien invasion — the distinctions between English and Inform need to be taken that seriously, by the writer of any manual, because that’s how seriously they need to be taken by the writer of an actual game. 87

Paul.

4

Two cents: I’d probably never have thought I could give IF writing a shot if the manual weren’t written the way it’s written. I’m not a programmer, and while I’ve a decently logical brain programming languages and programming manuals do tend to make me go wibble. Some people learn well when everything is laid out simply and clearly with definitions and short, sort paragraphs; some people, like me, learn well when things are written more naturalistically and are understood more gradually. So I think it’s great that people are writing manuals in other styles, but I’m glad we have the style we already do.

That said, I’m aware that this enables me not to write code, but to write sloppy code. My in-depth understanding of Inform is not great, so my code is not elegant. The accessibility of the manual has allowed me to start writing and is allowing me to get better through writing, rather than through just reading. It’s possible I’ll never quite reach the level of skill of someone who can pick up a more standard and clearer programming manual. But I don’t mind.

5

Jim: My classes all have the same problems with the manual you do. It’s why I had to write the “Well-Versed Informer” stuff so that I could start getting out the idea of “thinking in Inform.” (From a programmer perspective, this means design patterns. From a non-programmer perspective, this means heuristics and idioms of use.) In fact, when I tried to get Inform introduced into some curricula – a process I mentioned way back on RAIF – one of the first things I was always told was “The manual is going to have to be rewritten.”

Interestingly, unless I miss my mark, you have a writer mentality. (You did publish a book or two awhile back, yes?) As such, I notice that my class of writers often have the same cognitive friction that you do. And I, likewise, share that same set of issues. I mentioned in another post (in the game design area) that writers have an attention to detail and a mindset of making the fewest possible assumptions. I think that’s why some of us approaching Inform have some issues with how it’s presented. (One of my favorites is in 18.1, “On Rules”, which says: “We seldom need to know how this machinery [rules and rulebooks] works…” Really??!)

I could be way off here but I just find it interesting that your sentiments – and even the examples you often point out – are exactly the same ones that get pointed out in my classes. All that being said, having had to write the “Well-Versed” stuff did give me a feeling for how complex it can be to write a manual for Inform. However, it isn’t that hard if you keep forward references to a minimum and utilize a design structure for presentation, such as progressive disclosure, consistent use of nomenclature, limited and focused examples (rather than examples have “too much going on”), the use of exercises to encourage people to think about (and apply) what they just read, and so on.

6

I think this is referring to the previous example of a construction:

which is quite convoluted; not to any of the concepts that are being introduced in this section. I agree that it’d be nice to break down exactly what it means anyway (I don’t think those → things were in the old version, and zarf’s site is timing out for me so I can’t look them up in his index), but it’s not deliberately taunting the reader in the way that it seems at first, I don’t think.

I’m reminded the old joke about the math prof who says that some fact is obvious. A student raises his hand and says, “Professor, I don’t see why this is true.” The professor stares at the board for fifteen minutes, says, “No, it is obvious,” and keeps lecturing. – Anyway, I’m saying that it isn’t quite like that, since the thing that needs to be puzzled out is not the main idea of the page but a particularly convoluted example.

Also, this page seems to be new in this version of the manual, so it probably could stand to have some kinks hammered out.

BTW, count me with Harry as someone who finds this style of documentation an easier way of getting into the language than a more programmery style – I would never have been able to start with something like Ron’s programming guide. (I actually started by looking at an early draft of Jim’s guide, but switched to the documentation pretty quickly – partly because the draft I had was very early and I think didn’t even have some parts filled in yet.)

7

I can see the opening sentence of WI 21.1 being confusing in that it doesn’t seem to mean construction in the technical sense, so I’ve opened a bug on that: inform7.com/mantis/view.php?id=423 (let me know if you want to go on file as the reporter). But otherwise, construction'' can be read asparameterized type.’’

8

Interesting; I was unhappy with some parts of the Inform 6 Manual precisely because I thought it was not that rigorous, particularly in distinguishing what parts of “Inform 6” were properties of the language itself and what parts were properties of the standard library. (I remember in particular having a hell of a time determining where the implicit switch statement fell - I think it ended up being half and half.)

9

@Jeff: Thanks for the confirmation. Yes, I’m a writer – both a tech writer and a writer of fiction. But it does strike me that your description, “writers have an attention to detail and a mindset of making the fewest possible assumptions,” would (or should) apply equally well to programmers. In any event, if the documentation for Inform is being written by someone who is not a writer and/or doesn’t think like a writer, isn’t that a problem in itself?

I did like the Inform 6 Designer’s Manual a great deal, and still do … though on reacquainting myself with it recently I’ve noticed that here and there it suffers from the same tendency to blithely skip over details that really ought to be nailed down.

One response in this thread suggests that “construction” is not meant to be a technical term, while another response says that it’s a synonym for “parameterized type,” which is surely a technical term. Page 21.1 tells us that there are only nine constructions, which are then listed, so I would tend to lean toward the idea that the word is being used here as a technical term (without being defined). Yet it’s possible that the usage on page 8.16 is general, not technical, and thus misleading to anyone who is trying to puzzle out what’s going on.

@Matt: I agree that the style or tone used in “Writing with Inform” is more readily approachable, especially for novices, than the approach Ron uses. Ron’s guide, while extremely useful, seems to require both a prior knowledge of conventional programming (which is what he intended) and a prior knowledge of Inform 7 (which he may not have intended).

That said, I’m pretty sure “Writing with Inform” could be written in a much more thorough and rigorous manner without sacrificing the style and tone! That’s the challenge in technical writing – to make it complete and informative while also keeping it readable and clear.

After starting this thread last night, I started thinking I should try Zarf’s business model. I should offer to write The Ultimate Inform 7 Guide as soon as I have $10,000 in pledges. The resulting document would, of course, be free for users. If I can say this without sounding egotistical, I probably have as good qualifications as anyone to undertake such a project, including 30 years of varied experience as a tech writer explaining technical subjects (mostly music technology) to non-technically-minded readers.

Does anyone else think this would be a good idea? Or am I just swinging from a lamp post at 3 A.M., singing Irish ballads?

–JA

10

Sounds good to me. I’m of the mindset that if folks want to make money working in IF, they should ask for money straight out, especially if the goal is to enrich the community in some way. Kickstarter seems ideal for this.

11

I am really knew to inform as well and I find myself reading this http://www.musicwords.net/if/InformHandbook.pdf more than actually reading the documentation within inform 7. I am more of the programming type than the writer type and I feel the documentation is not designed to teach this type of person. Since I7 is based so much on English I think the right way to present it is to pretend the person that is learning is not an English speaking person. That way the verbage and such does not become to English like.

12

I could not tell from your context whether you are aware that the Inform Handbook was written by the original poster of this thread. But if you’re not, it’s worth pointing out… :slight_smile:

13

Jim, it’s worth a shot. I have no idea if you can get $10,000 out of such a project, but most technical books with traditional publishers don’t get that kind of an advance. You could always self-publish via Amazon CreateSpace / Kindle and continue to make money without a publisher anyways. (Do publishers even add any value when the distribution is a narrowly targeted audience? I would doubt it.)

My guess is a lot of folks would kick in $10 or $20 and some might go higher. So think carefully about keeping the scope of the project narrow enough to make it worth your time and effort and also so that people don’t have to wait too long to see it. (To me the value declines the longer it takes to get the project completed. I’d pay more for a 200 page manual sooner than a 400 page manual later.)

Sunday evening I would have pledged $100 for a ref manual if I thought it would have helped me fix the problem that had me stuck. By Monday evening I would have doubled it. Heck, if you are willing to do a code review of my game, I may go higher.

–Zack