I played a bit with Inform7 years ago. The only thing I remember experiencing was the disorientation of believing I could type in English (almost any logical sentence) and Inform would parse (the irony is not lost on me) the sentences and construct the logic behind the scenes. Then I became aware of what was really happening and was a little disappointed.
(Also, Iām not saying the following to be argumentative in any way.)
Regarding self-documentation, watch this short 5 minute videoā¦
(ā¦that channel has a few gems of short videos that I urge all programming minds to watch.)
Regarding reduced cognitive loadā¦ having the separation of language between story logic and story narration is a plus for me. Now Iām programming, now Iām authoring a story.
I still think Inform7 is a great tool, and one day I think Iāll dive deep into it. Anyway, just food for thought from an outsiderās perspective.
I have a question about Informās documentationā¦
Iām a self-taught programmer, mostly. I took one Java class in college and thatās it. I later learned Python (and teach it in HS now) and of course Inform 7, and I had a job making gameboy games in C++.
For those languages, I would do random internet searches when I was trying to learn something, but the examples were often either super complex (like including error checking and optimization) or very barebones and not really at the level youād use in an actual program. So Iād try to find open source code to cobble things together.
Informās large list of examples has been very useful to me, and Emily Shortās open source code. While I have bumped into problems with the documentation from time to time, Iāve found it superior to the random internet snippets I got when searching for help with C++ or Python.
But Iāve heard a lot of people say that Informās documentation sucks. I definitely found some problems with it while reading the whole thing recently, but like I said, itās better than what Iāve found.
So my question is, what documentation are you comparing it to? Do you have resources for other programming languages that you find superior to Informās documentation?
Iām partly asking rhetorically to prove a point but partly asking as a self-taught programmer and teacher who generally wants to be better and wants to have good resources to share with my students. What languages have good documentation, and what is that documentation?
I think the documentation is very good, but I found I had to read it more than once to get what was going on. It would be better if it started with an overview of what relationships are and how everything connects through them. Then explain how the statements create and alter relationships between elements of the story world. Relationships are fundamental to Inform, but they arenāt really discussed significantly until chapter 13. Way too late.
Also, if youāre coming from a programming background, you find yourself shouting just tell me the keywords and the syntax. All that information is there of course, but it feels buried.
Also, there is sometimes alternate phrasing of statements that do exactly the same thing and thatās confusing too. I know thatās to accommodate the different writing styles of Inform developers, but it does not help with concisely presenting the language. Inform feels so wide sometimes.
Think of the documentation as a study guide that has three hundred carefully and verbosely worked examples from, say, group theory, but never deigns to tell you what exactly a group actually is. Itās a recipe book, and that works great if you want to follow someone elseās recipe with minor modifications. (And as I mentioned above, the creators of I7 have definite ideas on what you should and shouldnāt be doing with the language.) If you want to understand how the thing actually works, or even just quickly look up the magic words I7 decided to make up for all the usual Computer Science 101 data structures and commands, itās a slog.
Honestly, for comparison, the DM4 for I6 isnāt bad. It certainly has its flaws (and it also relegates a lot of necessary black magic in the language to exercises or appendices, or even never mentions them at all), but I picked up the langauge from it without much difficulty. At the very least, it presented enough of the language that I could extrapolate the bits I didnāt know from what I did know. In I7, thereās an abstraction barrier imposed in both the documentation and the examples, and I donāt even know what to search for half the time. Also, frankly, the I7 documentation is designed for people who arenāt familiar with and even may be scared off from coding. Iām not part of that audience, and as such it doesnāt contain information I do want (e.g., lower-level details) and does contain information I donāt want (e.g., explanations of what numbers are).
Thatās pretty much exactly like this famous book, which I definitely wouldnāt recommend as a textbook:
I think I see your point. If you specifically want to know how to make functions, for loops, complicated if statements, etc., itās not really clear from the documentation how to find that and use that. I do think thatās somewhat intentional (because IMO traditional programming patterns donāt really make the best Inform games), but having obstacles presented to a reasonable method of study would be very frustrating.
This one. Inform does have a complete reference to its syntax, every phrase and its arguments and its return type, every rulebook and rule, everything youād need to referenceā¦
ā¦in the Index. Which isnāt officially posted anywhere online. Itās only available in the IDE. And you canāt access it until you compile a working program. The other documentation assumes that youāre reading everything with the IDE open and can check the Index freely, but if Iām trying to answer a quick question on my phone, I canāt do that.
If the Index were included as a standard part of the documentation, that were easy for me to reference online, Iād be much happier. (Some people from this forum have put it online, but Iām complaining about the official documentation, not what fans have put together to fill in the gaps.)
Not quite. I donāt really see syntax in there ā I see phrases. But that doesnāt tell me, for instance, how I need to phrase a description of values in order to get Inform to actually parse it (the problem in Inform that bugs me the most).
Are all his videos C++? I canāt tell or know, because Iāve never touched C++, and also he has no ABOUT information on his channel.
The first minute or so his anti-comment reasoning in this video is sort of obviated by Inform. He starts giving variables names using English phrases so that he doesnāt have to add a comment for his brain to understand what he was doing. Thatās part of his summary at the end of the video, too. āMake your code more humanā ā and one of the ways he does it is by slipping in more English.
There appear to be many good technical reasons in the middle of the video as to why not to use comments in C++ (Again, I say appear because Iāve never written C++ in my life). When he starts lecturing about how comments lie in general, I just will him to die in a sewer. There he can lie with his own crappy comments that lie to him, while me and my awesome comments that tell me the truth for eternity will carry on.
Actually, I expect comments do lie all the time in shared work settings. Consulting my memory, I know they do, because youāve got a pile of people all doing everything differently in both their brains and life. For my own programs, and when I share my own programs, comments are super-duper.
Ha, I actually recommended that book to someone else recentlyā definitely not as a topology textbook, but as a source of motivating counterexamples for the various separation axioms and other complications that arise in point-set topology. I like that analogy, though I could also argue that I7 is like the opposite of that book: Itās a source for examples for (what the designers consider to be) the most common and idiomatic situations that come up in game design, and youāre on your own if you want to do something more complicated or something theyāre not interested in.
I do think thatās somewhat intentional (because IMO traditional programming patterns donāt really make the best Inform games)
I disagree, but more importantly, I want to know exactly how I7 works and how I can use it to make the game I want, not the game the I7 designers think I should want. Itās one thing to relegate more complicated topics to a later section or appendix, but the I7 documentation goes out of its way to make it difficult to find certain information, even if youāre an advanced user looking for something very specific.
The video was merely to suggest the idea that regular programming syntax can be self-documenting. Itās not exclusive to Inform7. I wasnāt trying to suggest anything else.
Good documentation should let you predict how your program will behave. It would include a reference sufficiently specific and comprehensive that someone else could re-implement the language. We should know not only how things behave when theyāre passed appropriate arguments, but what the behavior is with inappropriate arguments: is there an error? If so, what? What else might happen?
If anyoneās a real glutton for punishment, pretend youāre a newbie who doesnāt know the answer to these and isnāt an expert on whatās where in the docs, so youāre relying on the table of contents, the general index, and searching. And you have access to a Project Index.
Scope seems pretty important ā what exactly is in scope when?
I entered ānorth, get allā and it worked! What are all the kinds of ways you can give commands?
How come my images donāt work when I release along with an interpreter?
What exactly can you do with glulx that you canāt do with the Z-machine and vice versa?
Does something hold another thing if the thing is a part of it?
Is it always true that if X holds Y then X also encloses Y?
Whatās the difference between the [something] and [thing] grammar tokens?
Whatās the difference between a visible thing and a touchable thing in action definitions?
Would a before doing something with the key rule be triggered when unlocking something with the key?
Iām getting an error when I try to refer to the actor in my activity ā what do I do?
For a rule using a named action pattern which of with <the thing>, in the presence of <the thing>, when <condition>, in <location> and during <scene> can I use?
When exactly is in the presence of true?
WI 16.7ās phrase definitions say (a table entry)ā¦ but where do I find out what are all the things that that can be?
Whatās 3 * 2 + 1? How about 3 times 2 plus 1?
Given To say t: say "", is the condition "[t]" is empty true?
How can I make a literal verb value for āto beā? verb be doesnāt work.
How come I canāt make āoā an abbreviation for āopenā and why am I getting this weird āSorry, that canāt be corrected.ā message?
I saw somebody say something about ambiguously plural ā whatās that?
Can I make a multi-word verb like āto look forward toā?
If you put a room in scope, an action applying to a touchable thing wouldnāt work on it, right?
Would something be in scope if it were undescribed?
In to-phrase arguments where you have (v - whatever), what kind of things can you use for āwhateverā?
What happens if I stop the action during a Carry out rule?
Can a non-person thing be an actor?
WI 3.20 was really specific that āwearingā and ācarryingā were different things. Does someone enclose what they carry?
Why is my relation of various texts to one thing not working when the exact same syntax works with various things to one thing?
Spoiler ā the result will be one of:
you wonāt find an answer
youāll come up with an incomplete answer
youāll find contradictory answers
youāll get a wrong answer
Iām sure someone could quibble with how relevant some of those are, or how reasonable or not it may be to expect to easily find an answer to it. But some of them are pretty important and for many of them it really should be trivial to get an answer without experimentation.
(And, no, Iām not suggesting that itās reasonable to expect a single developer to write something with the detail of the Python documentation. Iām separately addressing the question āwhat does good documentation look like?ā and giving examples of some of the I7 docsā shortcomings.)
[Edited: On reflection, I think one of the original ones is actually determinable, so I replaced it.]
Sorry to be so blunt, but ā¦ use another language, then? In all(?) other languages, the syntax is simply what it is. Language designerās prerogative.
Inform is peculiar in that it allows you to amend, and even change, the syntax of the language, but Iām not convinced that doing so would necessarily be a good idea. (Youād be giving up Informās arguably biggest advantage: the large number of people on the forum that can help you with questions.)
Many languages have a notion of āgood styleā, either as a community consensus, or (like Python) prescribed by the language designers. Inform is firmly in the latter camp, and it does not surprise me at all that the manual reflects those ideals.
Iām pretty sure that the Inform documentationās goal is not to be a dry Javadoc-style API reference manual. (Which does sort of exist for I7 in the form of the Index, as Daniel pointed out.)
So I donāt have many people to ask questions or bounce ideas off; itās much harder to find people to collaborate with; there are few extensions available, so I have reinvent the wheel in a lot of cases; I have to find an alternative for the the I7 IDEās packaging, because Iām only going to get about two dozen players with a completely frictionless setup and only a couple if thereās any sort of installation required; and so on.
Iām talking about the kind of game I can make with I7, not the coding style involved in implementing it.
I mean, plenty of people on this forum also have experience with TADS and Dialog and Adventuron and I6/PunyInform andā¦ And all of those can package their games into web pages, which is the ultimate āno installation requiredā.
Thereās nothing wrong with disliking Inform, but it certainly doesnāt mean youāre locked out of the IF community.
