trailblazing brickslayer [07/21/2007 05:52:50]

hard deadline

The brickslayer tutorial will open to the public on Sunday night, so I can free up time to work on the cornerhost source.

In order to visualize how much work I had left, I went ahead and created a jeopardy grid:

I'm following a stepwise refinement strategy here:

• define the list of iterations/lessons
• define features/headlines for each iteration
• isolate the code that implements each feature
• organize and refactor the code and narrative within the lesson
• clean up the subheadings, text, and html

Luckily for me, the columns on the right aren't nearly as hard as getting the code working.

untangling the gestalt

Actually, the code was more or less working months ago, but untangling the gestalt requires going back and creating small bits of extra code.

For example, the finished game starts with a title screen, but that screen doesn't get built until late in the implementation plan. So, early on there has to be a line that shows the game screen, and then later that line gets replaced with the line that shows the title screen.

The trail is a little bit like a version control system, because it contains both the finished code, as well as the historical (or in this case, retconned) "old" code.

Thankfully, there's not a whole lot of extra code to write. Most of the work was in hiding code - marking out lines that shouldn't have existed until later in the timeline.

the tool

Besides reconstructing history, I've written a 300 line python script to extract chunks from my marked up source code and merge it with an outline made with tinderbox and an HTML template to generate the tutorial pages and snapshots of the code for each lesson.

It's a pretty crappy system.

I do like having the narrative in its own file. You can mix code and narrative pretty easily in pure python (ex: narrative.py, but for web apps with a mix of languages, you want to show how the trail winds through the various files, and so the separate file really comes in handy.

Having the narrative in an outliner is really nice, because you can move the changes around in time. It's like having a series of patches that you can apply in any order.

Except they're not patches. Rather, the code is all there in one big tree that looks like a stripped down HTML DOM. Just like you can show and hide DOM elements with CSS, you can show and hide these sections with directives in the outline. Then at the end of each lesson a snapshots gets generated with only the code that has been revealed so far.

Here's what it looks like:

@:someCode
for each in series:
   do_something_with(each)
   @:notYet
   do_something_else_with(each)
   @:/notYet
@:/someCode

With that markup, you can reveal someCode, but someCode.notYet will still be hidden until you turn it on independently later.

The effect is nice, and the system is flexible, but adding all that markup is incredibly tedious. What I really want is a tool that combines outlining, code editing, and a theory of patches all in one spot, so I can see the narrative and the gestalt simultaneously, and move back and forth in time while I edit.

But that'll have to wait. I've got a tutorial to finish here.