A Different Approach to Inform 7 Documentation: A request for comment

Authoring Inform 7
,
1

The open-sourcing of Inform 7 has inspired me to resume work on my Inform 7 documentation project. I believe Inform 7 is a challenge to learn for most people, and different approaches can be a big help in understanding how to build rich worlds.

I am not a big fan of the official Inform 7 documentation, for one simple reason: it’s not easy to find out how to do basic world building! Why? There are no examples.

There are examples in the cookbook but they’re generally for a much more complicated case and don’t show how they change command responses.

My idea is to bridge the gap: to give newer users an entry point to understand the basics and have usable examples of how to do the most basic worldbuilding. I’m also attempting to make it reasonably fun and not too dry to read so people can scan it and know where to come back to when they get stuck.

I’m calling it Inform 7 At Play:

I would love as many eyes as possible on this early, incomplete version, to help me stay as consistent and high-quality as possible. What I’d love to know:

  • Did you find any errors, or anything that’s unclear?
  • What should I spend the most time covering next?
  • Do you have any good examples of “common mistakes” and errors you find people run into a lot?
  • Are there any other sections I could include?
  • What can I do to make this even better?

Also, I’d love to know what people think of the format. I’m writing in Markdown and putting the results on Github for the moment, but Markdown code blocks in Github don’t text-wrap so they’re almost unreadable in mobile. At some point I may use a Github action to format and publish this as a more custom website.

13 Likes
2

I hope you keep it up; it’s always nice to see more documentation!

1 Like
3

Interesting project! I haven’t looked at everything yet, but the format and style work quite well, I’d say.

I’m not as big a critic of the official docs as some others are, but it surely can’t hurt to have more learning material with different approaches available, especially since there are conflicting demands… some want the docs to be more like a tutorial, others more like a reference; some like the writing style, others don’t, and so on.

I feel like chapter 3 of the docs is intended to convey the basic worldbuilding information, covering much of the stuff one would need to populate a simple game with rooms, doors, containers, people, food etc.; and the examples below the main text illustrate how to do so, even though they also contain some material from later parts.

In the example for “Up and Down”, you write:

[[When you use north and south you can just specify one of the rooms is north and the other room with know it’s south. With “above” and “below” you have to specify both.]]

That’s not entirely accurate. With this code:

The little clearing is a room.   

The treehouse is above the little clearing.

… the connection will automatically be two-way, as expected, just as with other directions.

A one-way connection can be created in a specific circumstance, cf. 3.3 in the docs:

Finally, note that Inform’s assumptions about two-way directions are only applied to simple sentences. When the source text seems to be saying something complicated, Inform takes it as a precise description of what’s wanted. So, for example, in:

The Attic is above the Parlour.
The Attic is a dark room above the Parlour.

Inform makes guesses about the first sentence, and makes a two-way connection; but it accepts the second sentence more precisely, with just a one-way connection.

I don’t know the full extent of what Inform counts as “complicated”, but this (the addition of “[... is] a room [above ...]”):

The little clearing is a room.   

The treehouse is a room above the little clearing.

… will lead to a one-way connection. (This is the case in your example, which is why you have to specify both ways there.)

The same holds for other directions like north. This:

The little clearing is a room.   

The forest is a room north of the little clearing.

… will also lead to a one-way connection. (In Inform v10; in 6M62, the latter example doesn’t compile.)

Here are some related threads:

5 Likes
4

I look forward to following this project!

For example stories you provide, strip away extraneous comments and code not immediately relevant to the lesson. My biggest frustration with the official documentation is that the examples provided like to show off the potential of the things you can do with Inform, or telling creative little stories, but often forget to show you the basic code of the lesson. Don’t make me work to excise from the example all this other code I don’t need. Just show me the code I need! That’s why I’m here! I don’t need you to spark my imagination! (Sorry, I get cranky about this.)

1 Like
5

This is SO welcome.

It looks great, although I agree with @PatientRock-- strip out the extraneous stuff.

It would also be great to have links to the place in the docs where you can read more on those things. I have 3 big beefs with the docs: 1.) it’s hard to find things in them; 2.) Often the examples are too big and complicated; and 3.) There are some areas that are completely unhelpful because the explanations are too thin, or the format is just wrong, etc.

But the docs ARE helpful if you can find the correct search term, so link to them so people can zoom straight to the relevant section.

Thank you for doing this!

1 Like
6

I really appreciate the guidance… but can you give me an example?

7

Less of a correction, and more of a suggested guiding light. Inspired by the first thing I clicked on, “Making Actions”, after I saw the quip about Kyrgyzstan.

1 Like
8

Thank you so much for taking the time to make some edits and point me to some resources. I will make sure to make those corrections. Especially thank you for clarifying about the “up” rule, I was pretty perplexed by that.

1 Like