inform

ns that you have. It is _not_ to explain merely what your solution is and its parts—having already written it, but never having articulated concretely for the reader the problem driving you in the first place (if at all). This, too, is where most attempts to comment code fall short. I'm not getting any different feeling from Inform7. I can't help but feel as I begin trying to read through it that I've jumped into middle somewhere and have not actually started on page 1 since there's no way this narrative makes sense with that in mind. The file you linked to reads to me like any ordinary block comment where the author struggles to convey their deep understanding to someone else. Main.w in Chapter 1, after some attempt to be cute about the history of some procedures with similarly cute names like the "deputy", but nowhere explaining the problems that it will attempt to solve, starts right off[1] on line 30 by initializing four variables for which we have no inkling of their raison d'etre, but which presumably are supposed to make sense eventually, in true "Don't mind these" fashion[2]. It pretty much continues on in that vein—e.g. "@Start up the modules@" followed by a non-sequitur of a list of never-before-seen stuff (that, again, I'm sure will make sense eventually—once you've jumped in worked out the constraints and the "why" for yourself, just as you do with any traditional programming approach—but "literate" is not how I'd characterize it). The whole thing, I'd say, suffers from a real bottom-up* mindset—where we spend a lot of time on things we have not yet seen a use for (and we're not user we'll ever see a use for at this point, but which we give the benefit of the doubt for, anyway), when really what's called for is an explication that is ruthlessly top-down[3] in its approach. * unfortunately influenced, probably, by its roots in the culture of C—where you are forced to define things in a backwards sort of way, lest you have to add declarations for e.g. `bar()` before you're able to show in `foo()` how it is actually used—and where you tend to end up with `main` at the bottom of the file 1. <https://github.com/ganelson/inform/blob/e723c36deef41bea793a...> 2. <http://akkartik.name/post/literate-programming> 3. <https://www.teamten.com/lawrence/programming/write-code-top-...>