It seems the Tux Radar guys have been experimenting with Inform 7.
Not much comment about it in the comments section, but those comments I have seen indicate that people think the documentation is pretty poor, and that the example stories are too complicated to be of use. Hmmmm.
I have had issues with the documentation being less than useful, but on the whole I’ve got by fairly well, and the examples seem to be OK to me.
Thoughts?
I could not have learned Inform 7 from the included documentation alone. jim Aikin’s Handbook, Ron Newcomb’s I7 For Programmers, and countless answers to my questions on this forum have provided the bulk of my knowledge about I7.
I know the developers are busy, and I know they have plans to update the documentation when the spec for I7 is firmer, but in my opinion this model of creating documentation is not working. There are volunteers out there who would be willing to work on the documentation in parallel, and I think that’s a more effective model of development. Even if it amounts to more work, it means a more usable application at every stage of maturity, instead of some speculated perfect product that will be ready at an unspecified time.
But then, I think that’s part of I7 not being open source. I wouldn’t argue that it should be, but maybe they do need a slightly larger team working on it.
When you say “this isn’t working”, do you mean that Jim’s book and Ron’s book are not sufficient, or that the users who need them aren’t finding them?
Also, I’ve been working on I7 documentation (the index page) “in parallel”. Is this the sort of thing you want to see? Is it a part-resolution to your request?
(Feel free to push the index page on any forum where people are complaining about the I7 manual. It’s not quite finished, but I only have another couple of chapters left to work through, and they’re not core features.)
The thing about this is that there is (as I said elsewhere) no model we can think of that would accommodate gradual work on this. Volunteers could help with the creation of indexing and reference materials, or by providing wholesale alternatives to the core documentation – and many have done so, for which we’re grateful.
But it’s less clear how they could take up any significant amount of revising the core documentation, other than by offering usability suggestions. Anything that goes into Writing with Inform needs to be either written by Graham or heavily vetted by him for style, technical accuracy, and presentation; any structural changes that happen there will also have ripple effects to the structure of material in the examples and Recipe Book. This would pretty much lock down both his available Inform time and mine; for any serious overhaul, that would be an expenditure of months.
If what you are saying is “I would like to write some alternate documentation”, please, please feel free.
More of the latter. But it occurred to me that right now, this forum is an excellent place to find answers to questions in the short term. Maybe that’s perfect for now. I don’t expect this forum to be the place for fast answers forever, but maybe by the time it’s not, the collected wisdom of the users here will have worked its way into the manual.
Yes!! My main objection is again that it’s harder to find supplementary documentation than it is to find the documentation that comes with Inform. There’s good stuff out there, but I’m pretty bad at finding stuff.
I’ve never quite understood why information about IF is not more centralized. IFDB has changed a lot of that, but finding IF websites and resources still seems to take much more time and effort than I would have expected for such a small community. Seeing this forum mentioned on raif was a big leap for me - it probably got me more involved again after a few years of only marginally paying attention.
Me too! I’ve been working my way through the alternatives, but sometimes documentation is a situation where less is more. Reading three or four manuals to find one piece of information doesn’t seem like the best solution. Then again, as I mentioned in my previous post, at the moment we have something even better than a clear, concise, easily searchable manual: we have a cloud of experienced developers who are happy to answer specific questions about how to solve particular programming problems.
I mentioned earlier that the Recipe Book might turn out to be a useful reference. I’m sorry to say that I haven’t been able to grasp the organization of the Recipe Book any better than I have the manual, or in fact, the categorization of extensions on the website.
My next big hope is the Phrasebook. I didn’t know what it was until I came across a mention of it in something - probably Writing with Inform. I didn’t realize that it was a guide to Inform source syntax - I thought it was a catalog of phrases understood by the game parser. Sounds like a handy reference.
It’s a cathedral! (As opposed to a bazaar). It’s a beautiful one to be sure, but you’re right: as long as Graham has to be a gatekeeper for the documentation, its progress will depend on his availability. I don’t know Graham at all, but given the prodigiousness of his contribution to the IF world, he must be a serious workaholic. For us it’s a blessing, but maybe also a curse.
Thanks for the invitation, but at this point I’m not sure an additional alternate would have a positive effect on the signal-to-noise ratio.
Ideally, there would be just one good reference, but that’s not the only kind of manual worth having. I do think the existing different manuals serve different (and valid) purposes, as they’re trying to teach different audiences, and different people have reported finding different ones accessible.
Well, the extensions are (mostly) organized like the Recipe Book, so the two do go together, yeah. The idea behind the main manual is to teach someone starting from scratch the structures of Inform as a language; the idea behind the RB is to answer the question “how do I implement a ________?” where what goes in the blank is a command or a world model feature (as opposed to a relation or a list or a string of indexed text).
The Phrasebook is indeed meant as a syntax reference, systematic and self-updating based on your code. The down side of that is that it’s not necessarily much help to someone who hasn’t at least skimmed enough of WI to know about rules and rulebooks, phrases and assertions, activities, lists and tables, say phrases, and so on.
It’s a bazaar, as opposed to a cathedral. 
I still haven’t downloaded the new version, but it seems like a problem with this might be that the Phrasebook (and the rest of the Index) aren’t available until you’ve successfully compiled your code – meaning that it won’t reach the people who need it most.
This is supposed to be fixed in the latest build: the index from the last successful build should be retained for viewing.
That still leaves you at absolute startup, but I think there’s enough guidance in the docs to lead people to build at least a “Foo is a room.” game and see the results. If you haven’t read enough to know even that, you probably also don’t know what the Phrasebook is.
The error message if you don’t create a room is good about that. The last time I demoed I7, we got oohs and ahhs when we fired it up, hit “go”, and were immediately pointed at the next step.
Tangent, I know, but I wanted to laud that.