Writing and Exporting Feedback

On the TBX Forum, I was asked a question about the rubric I built a few years ago. I don’t use it anymore because I built it to grade in a style I don’t like or believe in. (Which was dumb on my part.) But I suggested I might make a video showing what I’m planning on using this coming term.

This seemed possible because I was thinking through how to cope with the fact that a lot of the brief in-person feedback I give throughout a term will, this term, necessarily happen online and in writing. What I imagined doing was sitting down to put my new system together and just recording what I did as I worked. When I was done, I expected I’d be able to cut out the lulls and moments of despair and post what was left.

The result I arrived at are the two new videos I’m posting today. Together they record me beginning with a fresh starter file and from there creating a form for offering quick feedback on small assignments that exports as a custom text layout. My total work time was about an hour and a half, but I’ve managed to cut that down to two twenty minute videos.

These will be the last videos for awhile: Day One looms, and the pressure is on.

Tinderbox Videos

It’s the time of year where I’m preparing courses for the Fall, and this year, I decided that I would make some videos demonstrating some of how I use Tinderbox to do that work. Two of these are now live. I’m hoping to make and post a few others in the coming days and weeks.

These videos are something I’ve imagined doing in a vague way for awhile and so they have been a long time coming. But in another sense, these videos are very much a product of the pandemic.

Classes are online for the Fall, and this has both increased the complexity of my preparations and forced me to do much more of them before classes begin. There seems to be so much to do and so little time to do it that it feels overwhelming. Making these videos offered me a chance to step back from that work and reflect on how I was getting started.

One important point: these videos are not instructional “how to” clips. Instead, they are a couple of brief looks at a few of the ways I go about my business.

Enjoy.

TBX on the Go?

Tinderbox only runs on macOS. There’s no iOS version. Generally, this is fine because if I’m going to work, I’m usually going to be working at my computer. The one major exception to this is when I’m drafting. This is tough work and I need to be able to move from computer to paper and back again, and I need to be able to decide that “this isn’t working” and to pick everything up and go to a cafe.

How’s this supposed to work if the research materials I need to reference while I’m writing are bound to my desktop? It occurred to me today that the obvious answer is HTML export.

When I’m writing, I never really need to change my TBX file. In fact, in a perfect world I would probably be prevented from making changes to it because it’s way too easy to sit down to write only to discover, an hour later, that I’ve produced a beautiful new map rather than 500 words. But here’s the thing: if all I want to do is to be able to read my notes, then it should be easy enough to just export and post them onto my server. I don’t even have to worry about whether the pages look good, right? They just need to work.

So to try this idea out, I copied the CSS and the main page template used in this blog into my research file. I wanted a template for each prototype (I’m using them to ID different kinds of materials) so that I could make sure that the appropriate information for each note would appear on the web pages that exported. To avoid making stupid HTML errors (I’m not a computer tech), I just kept duplicating and editing the main template I’d copied over from this blog. As I edited, I expected to be pulling info from attributes with value() statements, but I soon realized that, because I’ve been relying on links and link actions to organize my research ever since the new link pane was introduced, I could get most of the work done (and much faster) by using outboundBasicLink or inboundBasicLink to pull together lists of links by type. (e.g. Inbound links of type “directed” always originate with the director of the film.) 

After a quick two hours of work, I had a set of sensible HTML “notecards” that interlink like a wiki. I uploaded them to a folder on the server and voilà. A set of notes on the web.

Export is daunting at first, but once you figure out the basics (or at least, the basics that you need), it’s incredibly powerful and insanely fast. And so I walk away feeling like, with a bit of creativity and some careful thinking, I could make it do anything…

Moving a Course Online

Courses are cancelled for the rest of the semester, and colleges and universities are expected to provide students with a distance completion option online. Watching how that rolls out and seeing what it entails in my own classes has been revealing.

On a more global level, crisis has shown various powers-that-be for what they are. I’m thinking specifically of the contrast between the many teachers unions that have stepped forward to exert power by offering to help make things work better (without sacrificing teachers) and the very different approach of the few that have grubbed for power by trying to provoke the failure of administrators who are as overwhelmed by the pandemic as the rest of us. The details of how that’s played out on the ground is insider baseball and not interesting to outsiders. But my point is simply that crisis reveals character, and these are insights to be held onto for later.

On a more personal level, transforming a face-to-face course into something that can be given online in a compressed timeframe has been more involved and more complex that I would have imagined possible. I fully expected it to be difficult — just setting up and explaining how to use communication channels that are manageable with 120+ students reaching out every few days is daunting — but today as I was working, I started flipping through one of the legal pads I use for my realtime note taking looking for an idea I remembered jotting down. I flipped and flipped and flipped through iteration after iteration of inadequate idea after undeveloped idea until finally, suddenly, I found myself at the front page of the pad: I’d forgotten work had begun in a different pad. As I stood up to fetch the pad I needed from my other table I felt as if my labor was being gauged by page count: I hadn’t expected creating online materials to be a two-pad problem!

Now, after a few days of work, I feel like I’m nearly ready to send out documents, thankfully, and just in time: courses start back tomorrow. (Are my colleagues? I hope so. Whether they are or not, I’m confident they’ll manage.)

In my case — and this feels like yet another Tinderbox plug — the fact that I’d been playing in my course file early in term and had decided to track how each activity either taught, practiced or evaluated a ministerial objective proved to be a godsend. As I entered this information, it really could not have seemed more pointless: these basic governmental requirements are so basic that they take care of themselves in most courses. But in the current situation, being able to see plainly what had already been taught and evaluated allowed me to very quickly identify what remained to be done. If this information hadn’t already been readily visible in the links of my course map, the rabbit holes I would have fallen into and the herrings (red) I would have chased as I tried to figure out how to plan the abbreviated final weeks of the semester are quite literally innumerable. 

Process is Part of the Project

Québec’s response to the pandemic seems to be working. This is great news, but it’s also a sign that over the next few weeks there will likely be more of the quarantines and shutdowns that are keeping the pace of new infection so low. With this in mind, yesterday I decided to try to get some work done.

The dull anxiety of the past week — low-grade and barely noticeable, but there like a spare battery (remember those?) weighing down your backpack — had deadened my mind too much for serious reading. So I opened up the TBX file I’ve started for my new book project and decided to piddle. 

First off, I knew I wanted some notes that will serve as the starting point for some mini-analysis on early materials. I created them — simple titles with no text— and slipped them into my “To Be Filed” container. I’ll get back to them when my mind’s working better. 

From there, working in outline view:

  • I decided to organize some of the chaos in my initial bibliography. There are a couple topics I need to know more about as context. Book and article notes about them currently clutter my sources container — I can’t see anything else — but I know that they are quickly going to get lost as that container fills up with other things. So I created a note for each of these topics and went through my sources container making links to the notes for each of the sources that speak to those subjects. So I now have single note “index” pointing me toward sources as a starting points for when I’m ready to use them.
  • For the index note on the topic for which I have a lot of reading to do, I organized the list of links into sensible groups and then sequenced the groups in a sensible order. Now I have a reading plan ready when I eventually return to this.
  • As I was organizing the bibliographies, I went back to my mini-analysis note on Miramax and dropped in a couple links for important sources I’d remembered when I ran across them as I was working. I also decided to add a few sentences to the note explaining to myself what my interest in the company was (and wasn’t). Because I risk becoming seriously distracted and want at least some marker for later of what I initially thought it was I was doing. Then I jotted down some basic technical information I had at hand so I’d have it later without looking for it. It probably goes in its own note, but I’ll sort that out later.
  • I looked at some links between films, realized they were pointed in the “wrong way” — not that I’d made a mistake when I made them but that when I made them I’d been thinking badly about what they’d show — so I swapped them around. As I was doing this, I noticed some comments jotted in a few notes about allusions between some films and novels. Sorting out the direction of the mistaken links helped me see how I could formally link the notes for these alluding texts without “just linking everything.” So I made those links.
  • Curious, I selected one of these notes and switched to Hyperbolic view. As I poked around what is still a very limited link network, I noticed that some notes I expected to see there were missing. Switching back to the outline, I added links tying these notes into the network and then switched back to hyperbolic view. Now things were a mess — everything was connecting with everything — but I wasn’t sure how to fix it (or if it’s actually broken). So I left things as-is and went back to my outline.

Suddenly, my phone dings. My brother’s texting. I look at the clock and have been at this for an hour and a half. I scroll through the outline I’m working on. There’s still lots to do and I’m not sure how to go about it. However, things are better than when I opened the file in the sense that I’ve made some headway on clarifying my initial research questions and plans.

So I call it a day.

Outlines and the Terrible Beauty of Maps

After years of relying on map view in my TBX files, I’ve gotten to the point where I generally use outline as my default. The problem I have with maps is that they cue an aesthetic response that overrides other concerns, and I have trouble setting that response aside. A map is either beautiful and this creates a barrier to revision, or it is ugly and making it attractive becomes my priority. If I leave it ugly, then I find it hard to work in the file unless I stop using the map. Outlines short circuits this enormous weak spot in my mental make-up.

So when do I use maps now? Usually only when a file or project has developed to the point where I know what it is and how it’s working. I then create maps that operate either like a publication of key aspects or like an interface for interacting with attributes that change over time. In both cases, attention to aesthetics becomes an asset rather than a distraction because a beautiful map will likely be legible while being dense with information. Colors, shapes, borders, badges, even shadows can be used to communicate content at a glance, and in this context, attention to aesthetics makes them communicate clearly.

What this means in practice is that generally maps are for “reading” my materials, while outline and attribute browser are my work views. And hyperbolic view? I’m intrigued by it and flipping to it more and more, but I haven’t quite wrapped my head around what it does for me yet.

Crosspost: And then there were permalinks

I thought I’d wait to deal with permalinks, but I had an idea while taking a walk and decided to give it a try. Five minutes later they’re done. I always forget how crazy simple HTML export is. The key is to start with nothing and only build the things you understand. Then go from there.

I’m also not messing with an external CSS stylesheet. I just have a CSS note in my TBX file and a line in the page-head element of the templates that pulls that note’s text in as internal CSS for each page on the site. So I have all the advantages of external CSS when I’m working locally, but I don’t have to keep track of a stylesheet on the server. It’s the best of both worlds.

Crosspost: An Earlier Blog Experiment

I tried to run a blog from Tinderbox once before, but in that case, I tried to duplicate the look and functionality of my fairly complicated WordPress set-up. This meant building a TBX file that was a big hairy monster of a machine. I’m proud that I got the thing working, but running it took too much energy, and I wisely retreated to the CMS version of the blog after only a few days, lesson learned.

Crosspost: A New Blog

This is the first post of a new blog experiment that I imagine as a space for micro (and perhaps not so micro) blogging. It is also an experiment in building a simple HTML blog without WordPress or some other CMS operating as middleman. I’m doing all the writing and HTML generation in a Tinderbox file that’s simple but that should be able to grow (or not) as I need it to, unlike the last time I tried something similar.

Ordinary Human Language still exists and I may continue to write there. I haven’t decided yet. That blog began as a place where I posted book and movie logs, built a commonplace book, and eventually, began sharing thoughts about how I use Tinderbox. There’s a lot there. However, the blog is moribund, has been for awhile, and my attempts to bring it back to life haven’t been very successful. In part, the problem appears to be that, for the moment, I’m not very invested in posting the kinds of things that blog grew to focus on. Beyond that, I’m also just tired of having to keep up with WordPress to maintain such a simple site.

So this blog is a new start built up from an empty TBX file composed of: 

  • three template notes,
  • one agent, and
  • one container for post notes.

Things couldn’t be more barebones than this. Yet if you’re reading, it works. And all of it came together in a couple hours this morning.

What’s posted now is very close to the look I have in mind for the blog.The color scheme I’m using is based on Ethan Schoonover’s excellent Solarized. Currently, the blog appears as a single page of posts, which will be fine for a long while because I imagine this as a text-only space. That said I am also exporting posts as individual pages, and eventually, I intend to link to these from the post titles on this page in order to create permalinks. I might also set a cap on the post count for this page and create an archive for the overflow. I’ll see though. Any changes will happen slowly and in response to whims or bursts of inspiration.

Returning to the Fold

A year ago, I made the leap from Mac to PC by buying the pieces and building myself a gaming desktop. It was an impulsive move, motivated by too many years of frustration with the limits Mac hardware created for gaming. And I don’t regret it because no matter how often I play off gaming in conversation with casual acquaintances, it’s a big deal for me.

The stress point though was work: gaming’s fun but I use my computer daily for the grind and could I manage with a PC? Over the past year I discovered that I could, largely because Windows 10, unlike its recent predecessors, is a solid OS. And because my school is full-on PC land and the Mac-based fiction I’d dealt with for years disappeared, the jump to Windows was actually near painless.

The key word here is “near.” 

The main problems? First: junkware. There are a lot of sketchy apps in Windows world and I’m just not interested enough to sort out what’s what. Macs feel secure and I believe Apple is interested in keeping them that way. Windows and Microsoft? Not so much. That may be out-dated prejudice given the changes in security features in Windows 10, but suspicions kept me close to the base system for much of the past year.

Second: buying Windows equivalents for Apple software is expensive. People gripe when a Mac app costs more than 10$, but spend some time in PC world and you’ll realize that the apps offered by Mac developers are a bargain. Even the “expensive” ones.

Third: Eastgate’s Tinderbox. I’d had periods in the past when I was confined to an iPad and have written about how difficult it was to do my work without Tinderbox’s various tools, most of which I’d come to take for granted. Those earlier moments had been temporary disruptions. But now, working on a PC, they became my new normal, and after a year of genuine, wide-ranging and eventually desperate experimentation, I realized I missed the software badly. I’d become something like a mental-cyborg used to lifting cars, who now suddenly, alarmingly, finds himself fully organic and stuck lifting groceries. Or maybe some over-filled garbage sacks. I’d grown used to thinking in a way that assumed that my info could be organized into forms I could think about. It was a constant annoyance (and also a real impediment) not to have the tools at hand to make that happen.

But I just sprang for a new MacBook Air—!!!!—and so I am now happily on macOS once again. My first thought: thank god. Yes, my Tinderbox query and action syntax is rusty (very!) and I’m having to find my way back into the forums and the TbRef, both of which feel for the moment like navigating a train station in a language I don’t quite speak. But I don’t care. As I’ve said elsewhere: TBX is powerful enough to be game-changing even with only it’s simplest tools in play. So it’s worth it already and I know the pay-offs will just get bigger as I fall back into the groove.

So for the record my current set-up, which seems close to my ideal, is a PC desktop for gaming and a MacBook for work. (iOS, as tempted as I am to be tempted, is a distraction and a dead-end for me. It’s just not part of the equation outside of my phone.)

And since it’s Thanksgiving in the States, let me say: I’m lucky to have the means to buy and maintain both systems.

Cyborg. Thinking.

When I think of cyborgs, I think of metal men, bodies run through with hardware and silicon. Sometimes, if I’m feeling expansive, I think of it in terms of “the web + search” or of “the cloud.” These make the hardware metaphorical: the silicon is elsewhere, I access it from a distance, and so my body–my cyborg me–is now the biological-technical information system as a whole.

In both versions of the cyborg, the interface between self and hardware is embodied rather than mental. This is more overt in the image of the metal man but is just as real in the information system cyborg. There the mind remains intact, biological, while memory–envisioned as storage distinct from and accessed by the mind–becomes technological.

After nearly a year away from macOS, I’ve now returned, and in doing so, I realize that I’ve never imagined the cyborg that I’ve become because it is precisely my mind, my manner of thought that has been run through and transformed and by software rather than hardware.

I’m talking about Tinderbox. It is a tool, but after habituating myself to the slog and resistance of other tools these past 10 months, I’m especially sensitive to how my mind works differently when that resistance isn’t there. I now see that I know and understand more–and as a result am able to think better and to greater effect–when I arrange my projects in Tinderbox’s hypertextual world. I struggle and hit roadblocks, yes, and these arise from hitting both the limits of my control of the tool and the limits of my thought’s development, but these roadblocks sit further out then I can easily go without Tinderbox.

This last is what I find most striking after a few days back on macOS: my mind, my thought, my very act of thinking has been run though, enhanced and even transformed by software. This is cyborg-ism that matters and suggests that my early analogy between Tinderbox and a pencil is too timid. Tinderbox is writing.

Tinderbox RSS

This blog isn’t a tech blog, but I write about Eastgate’s Tinderbox semi-regularly.

To help those of you who are interested in the TBX posts but not necessarily all the rest, there’s now a link to the TBX-only RSS in the sidebar. (Or click here.)

ps—I suppose this is fair warning that the next few posts involve me over-investing in not-fancy TV and movies.

Exporting Text from Tinderbox

At the same time as I was finishing up work on the new version of my site using Tinderbox, a few threads popped up on the Tinderbox forum talking about the perceived difficulty of Tinderbox export. This got me thinking yet again about the source of all the trouble. At various times and in various moods, I have both agreed export could be a pain and been astonished at how easy it made creating complex documents. Thinking about it again led me to jot down metaphorical thoughts about car dealers and Mad Libs. I also tried to describe what I see as the fundamental difference between TBX’s export and other common tools.

Once I had those ramblings out of my system, I decided to use what I’d learned making my web site file to offer up a short series of posts that tries to show how I’ve come to think about basic export. Obviously there are other examples, instructions and information about Tinderbox available elsewhere. (The TBX help files, Mark Bernstein’s The Tinderbox Way, Mark Anderson’s TbRef,  Welcome to Sherwood, and the videos of Dominique Renaud are only a few). I try not to repeat that work here.

a map of the series

Instead, what I’ll try to do is show how working backwards from the desired output rather than forward from a note is a useful (and manageable) way to think about export. In my opinion, working this way resolves a lot of the difficulty I initially experienced.

Each of the examples in these series will begin by creating a concrete instance of the desired output. Once this instance is written, I show how to transform it into an export template that will generate the same output from any note. I’ll be using the same sample file throughout (download .zip).

You should start with exporting a form letter. All the other examples take the information it provides for granted.

You can find the rest of the examples here:

In the next few days, I’ll close out the series with a few thoughts about what’s involved in exporting to the web.

The New Site: un bilan

The last few months I’ve been working on moving this site off WordPress. That meant transferring all the posts to Tinderbox, setting up all the links, and creating the templates that would produce the HTML output I wanted to have. Everything except the templates was donkey work and took days and days. The templates took time as well, but I was learning about export and HTML and that was useful and exciting.

And when I was done, the file worked like magic. All my posts were suddenly arranged in a sensible way based on content rather than chronology. I could build up links (both href and visual) and could write outside the framework of a timeline. I began to imagine ways of writing that involved something I thought of as “portal posts”: single posts that would appear on a blog timeline but which opened into a system of pages—a kind of mini-, discrete hypertext—accessible only by way of that initial post. I wrote the first of these to explain some of what I learned about export. (It looked like this.)

Then I uploaded the site with a welcome message and the first of what I hoped would eventually be many of these portal posts, and almost immediately, I realized I was in trouble.

The trouble is that I’m a tweaker. (No, not that kind of tweaker.) I like to fiddle and change things and I do this continually, everywhere on this site. There are posts on this blog that I wrote in 2011 that, when I looked at them while preparing my TBX file, were revised to fix problems I found. The movie log of La Mort de Louis XIV that posted less than 12 hours ago? WordPress currently lists 28 revisions to that post.

Once I posted my site, I immediately saw places to fiddle and since that’s half the fun of the site (maybe more), I fiddled and then re-exported and re-posted the site. And then I did this again and again and again. Then I started trying to just replace individual files. This quickly became complicated: I was doing it wrong and breaking things. I didn’t know enough about what I was doing on the server to be sure how to use the output TBX was providing. I’d fix things and then mess something else up.

This was fine: I was learning and I was sure that eventually things would become stable. I’d figure out what to do and become practiced at it. But at the same time, I also realized that I didn’t know enough to predict when I’d reach that moment of stability. I suspected though that I knew little enough to guarantee I’d be learning by crisis-management for a long while.

Clearly I was in over my head and was going to be spending tons of time figuring out basics on my own. I knew too that my patience for floundering with mechanics when what I really wanted was to be working on content would be very limited. So I gave up on the whole “manage a site manually” plan and went back to letting WordPress do the heavy lifting.*

Yes, that means dealing with the limitations of my chronological timeline, but I’ve got an idea about how to make my portal post concept work. What I’m leaning toward is to use my TBX file—which I now know works—to create and to export these tangles of notes with this change: I’d write their intro page with the starting links as a post on my timeline and all the rest sitting as flat HTML files in a subdirectory. I’m still thinking that through though, and so we’ll see. For now, the export posts I wrote for the now-defunct “new” site will appear here as a series. Not great and not what I’d intended, but better than nothing. This series—posted here as I’d imagined it working on the new site—starts with this post.

And so that’s what happened and where things stand.

Onward and upward.


* The other factor was that a lot of the donkey work on the new site wasn’t done. I had all the post texts and links, but most of the images and videos were missing. Adding them back—and I wasn’t willing to lose them—was going to take a lot of time. It wouldn’t be worth the time to add them if I soon ditched the HTML site because I couldn’t maintain it. So there was pressure to make a decision quickly. With my quickly emerging sense of how to little I actually know about the running a web site—I’ve still not figured out how to make a relative URL from the root that works to throw out one (I thought) simple example—sticking with WordPress was the safer bet.

Big Changes in the Works

For awhile now, I’ve been working to migrate this site off of WordPress. This has happened behind the scenes and has been slow going. The new site isn’t complete—most of the images still need to be placed for example—but all of the text is there and everything is functional.

What that means is that now I’m sorting out when to make the jump from here to there and how I’ll cope with the inevitable change in permalinks that I lack the skills to deal with invisibly (if that’s even possible).

The rough and still evolving plan as it stands now is:

  1. to place the new version of the site in a subdirectory for a while and to publish a link to it here. This will give me a chance to see if things work for real and for people to see the change is coming. Once the link to the new site is published, all new posts will be published there and this site will go dormant.
  2. to set up the new site to serve the root address and to displace this WordPress blog to its subdirectory. I’d publish a link to the old blog’s location on my new site. The date for the move will be announced here before it happens but will probably be in the week following step one.
  3. to write up a series of posts explaining how and why I’m going to use Eastgate’s Tinderbox to manage the new site.

So major changes and exciting times.

Stay tuned…

Challenges Exporting in Tinderbox

A thread on the Tinderbox backstage forum has touched on export and its difficulties. I’ve written here that export is surprisingly easy, and I still think, in practice, that it is. Yet there are real conceptual difficulties that can also make it feel mysterious and intimidating.

I’ve been thinking about export a bit these past weeks because I was so dissatisfied with my explanation of how my grading rubric worked. Rereading what I’d written, I saw that I had never managed to figure out a way to explain how I thought about export. So what I wrote wound up assuming that the person reading already knew much of what I hoped to explain. I’ve been trying figure out what I would have needed to say in the weeks since.

What follows is my tentative list of what I see as my conceptual challenges as I started dealing with export. They are not shortcomings in the export process itself.

Experience

I mentioned this difficulty in the backstage thread, and it’s pretty straightforward: I know how to organize a word document because the arrangement of info on my screen is synonymous with its arrangement on the printed page. My output is organized by my workspace even in programs as flexible as Scrivener: ultimately, the sequence I impose in my binder determines the arrangement of my output document. If I want a different output, I rearrange my workspace.

TBX notes and output don’t march in lock step in the same way. They can (and do in the built-in templates) but the in-doc organization of notes and attributes will often be largely independent of export results. That makes TBX stand out: I can’t think of another program on my computer that divorces workspace from output organization in this way. The separation is powerful but uncommon enough that, when I start a new export, I lack personal examples or comparable experience to draw on and feel adrift (at precisely the moment—“Print!”—when I usually feel done).

Direction

I should say right off the bat, that this problem may actually be simply a misunderstanding resulting from my lack of comp sci training. It’s persistent enough that it feels real though. I’ll explain with an analogy to a stamp action.

Assume I have a note with two Attributes $A and $B with respective values of 1 and 2. I make a stamp with the action $A=$B and apply that stamp to the note. The two Attribute values will now be the same. But will the values both be 1 or will they both be 2? The action’s behaviour is stable and unchanging. So there is a correct answer. (I think it’s 2?) But my point is this: the direction of the equals sign is neither implicit nor obvious. It’s arbitrary, and ultimately, you just have to learn it. Which is fine because I have no natural sense of the direction of the equals sign.

I do, however, have a sense of the natural direction of export. In my experience and in the common understanding of the word, export moves from me (and my data) and toward something (or someone) else. I send a document to my printer, not the other way around. As a picture, my daily experience of printing is:

[ME with my organized info]    ::push:: ==>              [printer]

TBX export feels to me like it works in the opposite direction. I start the process by creating a template, the symbolic image of the output I want. This image is built up by pulling information piece by piece from my notes and then rearranging it for export. As a result, TBX feels like:

[my organized info]       ==>::pull::     [ME organizing a template of desired output]

The shift in direction from pushing to a printer to pulling from notes seems like nothing, but I think it’s at the root of a lot of my uneasiness when I start a new export. Things are flipped over onto their head.*

Templates

Tinderbox hides a very unusual, very peculiar thing under the familiar and innocuous word, “template.”

In most common applications, templates are where you turn for an easy solution. Need some colors that match in a document? Pick a template. Have to write a report and don’t know how to format it? Pick a template. And when you go to choose the templates, you are presented with a preview image. WYSIWYG!

TBX templates are nothing like this. Most obviously, they aren’t pre-fab except in very basic forms included for import. Instead, you make the template you need in order to produce the output you want. This is great and powerful (Oz-level great and powerful even), but different from the common experience.

Less obviously and less trivially, templates:

  • are usually a system of notes (rather than a single object) structured hierarchically using path names;
  • produce output as a collage of your data using instructions that are distributed across the system of notes:  your output is a product of interactions across the system as a whole;
  • represent the desired output symbolically rather than mimetically. This shift from image to symbol is extremely powerful but it makes greater cognitive demands on the person confronted with the symbol. It can be challenging, for example, to understand the connection between the distributed instructions I’ve placed in a template and the output preview visible on the “preview” tab. (I teach literature and see this difficulty “reading through” symbols play out every day in class.)

Taken together, I think all of this highlights that an uneasiness with export may express a pedagogical need rather than a technical failing.

Translating Computer Science

I wouldn’t want any of this to seem to suggest there is anything wrong with TBX export. I don’t believe what I’m describing here arises from technical or interface difficulties (or at least none I could imagine or suggest a solution to). They seem to me to be conceptual.

TBX takes what this layman considers to be high-order computer science concepts and translates them into a tool I can use to great benefit. But translation will only get me so far. Ultimately, I have to wrap my head around how the tool works, and the information I need to do so (HTML, CSS, page-layout concepts, etc.) may be out of scope for a TBX tutorial.

Export is powerful tool and, when I’m done it with, feels like it was technically easy to manage. But an important aspect of that power is completely (and refreshingly) unfamiliar: TBX asks me what I want it to produce and stands ready to make anything and everything that I have so far asked it for. But answering that initial question—what do I want?—positively and for myself (rather than simply selecting from a range of choices) is disorienting because I’m so seldom asked it elsewhere. And so I’m often still wrapping my head around what my answer might be when I sit down to make a template.


*–rereading this it occurs to me that it might be useful to think of TBX as operating a bit like an old newspaper. There’s my workspace which is the newsroom with all the action that entails. But then off to the side, out back maybe, there is layout and the printshop, which together compile, label and produce the day’s paper.

In terms of the analogy, I never actually “export” anything. I’m really just sending the work I’ve got at a particular moment over to the printshop for inclusion in the most recent edition. And that edition will, obviously, be organized according to constraints and goals (page count, ad space, etc.) that have little to do with how work is organized in the newsroom.

Exporting Comment Sheets

This is my final post about my grading rubric, and I’m going to use it to explain how I set up my export template to create comment sheets. But before I do that, I’m going to take a moment and explain why I think export can seem difficult. If you’re not interested, you skip it.

Export Expectations

I’ve commented elsewhere about discovering how simple and flexible Tinderbox export is. I still believe this is true. Yet, every time I sit down to export something new, I find the task daunting. What gives?

I’m convinced the problem is conceptual and arises from the uniformity of the export function in every other application I use. In those programs, export is called “Print” and it functions in a single, predictable way: from top left to bottom right, line-by-line. Most importantly, this export generates a copy of the arrangement of materials visible on my screen. The trade off for this simplicity is that, because document organization and export organization are synonymous, I must organize my document according to the fixed rules of printing. (This is a constraint we all live productively with most of the time.)

Tinderbox does not work in this way. I can organize my notes however I want and from that organization create whatever export file I want. Working in a file and exporting from that file are largely independent process. In a lot of ways that’s a very good thing. Something like my course map wouldn’t be possible if I were constrained by the rules governing “Print.” The cost of the flexibility can, however, feel considerable when the few default export options aren’t enough and I’m confronted with the problem of how to imagine and to create a “Print” that is adequate to my needs.

Oddly enough, I don’t think that the difficulty involved in coming up with “Print” is found in the export code. In my opinion, export code is much simpler than agent queries and action code. So what’s the problem? Crazy as it sounds, I think it’s having to decide what I want to have once my export is complete. I don’t have to do that in MSWord because — like Henry Ford and his Model T — Word gives me one option: a series of 8” x 11” pages printed top to bottom that match what I see on my screen. TBX is no Model T: the available options are seemingly, overwhelmingly limitless and choosing is hard.

Getting Started

My trick for getting past this block is to step away from my computer, to grab a pencil and paper, and to sketch out what I want. Once I know that, I’ve found that making TBX give it to me is pretty easy. And if I change my mind and want to tweak something? That’s usually easy too.

For the comment sheets I was exporting from my rubric, I wanted various note texts and attribute values to be collected and presented in a sensible way. I thought about this in terms of the rubric hierarchy and came up with a structure shown here.

 

What I Need
General Structure

In this image, the yellow box would be summary information, all of which I had stored in the root note of each instance of the rubric. The green boxes correspond to information stored in various attributes of the criteria notes; the blue boxes are my comments, stored as note text in the descriptor I checked while grading. To create this output I’ll use three templates all of which will be based on the basic HTML template provided through the FILE menu.

Before getting started with the templates, I should also mention that my pencil drawing of the comment sheet indicates where in my TBX notes the information I want to export is located. To give a sense of what that means, I’ve taken screenshot of my sample comment sheet and used colored boxes and labels to do the same thing here.

Annotated Comment Sheet

Templates

I import the html templates that comes with TBX and use them to create my starting templates by copy/pasting them as I need to. By the end of this process, each note in the rubric needs to have the appropriate template assigned to it, either directly or by the export code. To assign them directly, you can use either the HTML tab of the inspector (cmd-1 then the tab marked”< >”) or the HTML selector tab above the key attributes in the text pane. (If the selector tabs aren’t visible, you can turn them on with “WINDOW–>SHOW TEXT PANE SELECTOR.”)

t_comment_sheet

My first template is assigned to the root note. It collects and arranges information from this using three basic export codes. These are:

^title^
^value($RubricEssayGrade)^
^text^

^title^ and ^text^ are easy: the first prints the $Name of the note (which my rubric prototypes have already set to the $ExportFileName) and the second prints anything I’ve written in the $Text attribute (which is what is displayed in the text pane). These two codes are special: they pull the information in $Name and $Text without requiring the attributes to be named. For all other attributes, you use ^value()^, placing the attribute name in the parenthesis. In my template, the ^value()^ code will insert the student’s grade for the essay.

If these three terms were simply listed in my template, then the export would be an unformatted list with no context and would look sloppy. To fix this, I add some stock text — a “/100” after the grade and a generic introduction to the criteria comments — and format everything using html tags. My understanding is that most (all?) html tags will be recognized during export, but I only know a few. So I can’t say for sure. Text added to the template will be added to the output as typed. No codes necessary.

Finally, I want the export to include more than the root note of my rubric. So I need to indicate that my criteria notes should be exported as well. These criteria are the children of the root, so I can use the command:

^children^

That one command is enough to tell Tinderbox to include each of the children in the export. And what information about the children will it include? Whatever the child’s export template says should be included. In my template, I assign a template for the children’s export in the export code by adding a parenthesis to the ^children^ command. But if you’ve assigned the correct template to the criteria using the inspector or the HTML selector tab that’s not necessary.

This template will generate the text found in the red, the blue and the first two green boxes in my image above and, assembled, looks like this:

Comment Sheet Template
Comment Sheet Template

t_comment_sheet_category

This template controls the export of the criteria notes. It uses the same export codes as the previous template, and uses similar html tags. The stock text is different and integrates an attribute value in a more interesting way, the path for the template used to treat the criteria’s children has also been updated, but otherwise, it works in exactly the same way.

This template will generate the text found in the pink, the orange, the brown and the last green boxes, and, assembled, looks like this:.

Criteria template
Criteria template

t_comment_sheet_text_item

The final template, which controls the export of descriptor comments is a good example of the daunting/easy paradox of export. On the one hand this template needs to do only one thing: export the descriptor’s note text. To do this requires nothing more than the single export code ^text^. Easy-peasy. (I spice things up by adding the stock text “Your essay: ” before the comments text because I want things to look classy.)

But there’s a hitch: I only want to export the text of the descriptor note I checked when grading. ^text^ on its own will include all the descriptor comments whether I checked them or not. I don’t know how to do that. So it’s off to the TbRef and the user forums because there’s no way to intuit the answer. I know I need an export code that does the same thing as the action code I used when doing calculations, and I have to look or ask until I find it. It doesn’t take long, but if feels harder — and is more daunting — than selecting “Print.” Once I have the command I need — ^if($Checked==true)^ — I add it and everything works.

The resulting template generates the olive box above, and although it has felt like the hardest to make, it is only two lines long and pulls information from only one attribute. So it is actually the simplest and the shortest of the three.

Descriptor Template
Descriptor Template

 

Final Step

In practice, when I’m done grading, I move all the rubrics from out of the student containers and into a new container that, when I export, will be a folder with all of the correctly named comment sheets inside. I batch convert these to pdfs and upload them to my college’s course management system and students can consult them from there.

The one hitch I see in this output is that the default text sizes for the text is large when printed, but I haven’t decided if I want to do anything about that. If I decide I do, I think that all that’s required is a simple html command in the root template. But that said, I’m pretty sure my students reading their comments on a screen rather than on paper which means there’s probably no problem.

Rubric: Calculating Grades

Grades are calculated automatically in my grading rubric using attribute values assigned or calculated at each of the three levels of the hierarchy. So to explain how it works, I’m going to start with the lowest level and move up to the highest.

Before I do though, it’s perhaps worth noting that these calculations use the $Checked attribute. If checkboxes aren’t visible in the outline, you can show them by going to VIEW ==> USE CHECKBOXES. Or if you prefer, $Checked can be set as a key attribute in the p_rubric_component prototype.

Descriptors

Basic grade values are established here by selecting one of the available descriptors and ticking its checkbox. If you wish to change the default point value of a descriptor, you may do so by entering the new value in the key attributes. The rule presented in the previous post will update its $Name to reflect the new value.

Two things are worth noting:

  1. Once the grading is done, there should only be one descriptor checked per criterion. The final step in the grade calculation is a simple sum: if more than one descriptor is checked, the student will be awarded points more than once for that criterion, and their final grade will be higher than it should be.
  2. The criteria and final grade calculations that I use assume that each descriptor is evaluated by a point score between 0 and 10. If this isn’t the case for you, you’d have to adjust the calculations.

Criteria

The criteria-note calculations take the point value of a checked descriptor and multiply it by its criterion’s weight to determine the points awarded toward the final grade. (See note on weighting below.)

To generate my weighted grade, I need to multiply the assigned grade — stored in the selected descriptor’s $RubricPointValue — by the criterion’s weight — stored in as the criterion’s $RubricCategoryMax value. The simplified calculation that would seem to perform this multiplication (but doesn’t) looks like this:

$RubricCategoryPointValue=$RubricPointValue(child)*$RubricCategoryMax

This tells TBX to pull the point value stored in the child note (i.e. the descriptor), to multiply it by the criterion weight stored in the criteria note, and to store the result in $RubricCategoryPointValue.

However, there is a problem: each criteria has more than one child. This rule doesn’t care about that and simply calculates the weighted value of the first child, whether I’ve checked that child or not. To make my rubric work, I have to tell TBX that it should use the $RubricPointValue of the child I have checked and to ignore the rest.

Using Mark Anderson’s TbRef, I discovered that the way to do this is to use “sum_if(x, y, z)” which I found very intimidating at first but which I’ve decided is not as complicated as it seems. As I understand it, this command tells TBX to add up numerical values that match a set of conditions (or arguments) laid out in the parenthesis. There are three types of conditions possible, and I’ve labelled them x, y, and z. (I don’t know if all three are required but I use all three of them in my calculation.) What they stand for is this:

  • X tells TBX which notes to look at by indicating a location. For example, I could replace X with “all” and TBX would look at all the notes in my project, but for my rubric, I only need my calculation to consider “children.”
  • Z tells TBX which attribute to look at. In my calculation, I want TBX to see if a descriptor note is checked or not, so I use “$Checked” for the value of z.
  • Y tells TBX what value it’s looking for in the attribute it’s examining. Now I’m sure this argument allows the initiated to do incredible, magical things, but thankfully I only have to ask TBX to look for checkmarks, which is a boolean value — yes/no, true/false — and so, I need nothing more complicated than “$Checked==true”.

Combine these three conditions in a parenthesis, separate them by commas and then use them to update the equation presented above and you have:

$RubricCategoryPointValue=sum_if(children,$Checked==true,$RubricPointValue)*$RubricCategoryMax*0.1

This looks complicated enough to make my heart flutter and my stomach ache, but it works and in a weird sort of way is logical. You just have to work up step-by-step. (…and ask questions.)

Regarding the final term of the equation (“*0.1”): because I use values from 0 to 100 to define criteria weighting, I have to multiply the product of my calculation by 0.1. If I don’t do this, the final grade calculation will report a grade of 88/100 as 880/100. Defining criteria weight with a scale of 0-10 would eliminate this problem, but I prefer thinking of weighting as percentages, which is more natural with a 0-100 scale. Multiplying by 0.1 moves the decimal point to where it belongs.

The Criteria-level Rule
The Criteria-level Rule

This calculation is stored as a rule in the p_rubric_category prototype, which then automatically applies it to all criteria notes in all instances of the rubric.

Final Grade

In my rubric, all the heavy lifting happens at the criteria level. Once the weighted point values are calculated and stored in the $RubricCategoryPointValue attribute, all that’s left to do is to add up these weighted values. To do this I use the “sum(x,z)” command. In this command, X and Z function in the same way as they do above. No Y argument is necessary because the command isn’t evaluating a condition in order to determine which values to add: “sum(x,z)” adds all the values found at the designated location.

As a result, the rule that calculates the final grade is simpler and reads:

$RubricEssayGrade=sum(children,$RubricCategoryPointValue);

The result of this sum — which will always be a value between 0 and 100 — is the final grade of the essay stated as a percentage. It is stored in the $RubricEssayGrade attribute where it is used to set the rubric’s $Subtitle and $HoverExpression.

The Root-level Rule
The Root-level Rule

And that’s it for the grade calculations. In the next post, I’ll explain how I export the rubric as a comment sheet for students.

****

Note on weighting

If all the criteria were weighted the same or if the descriptors awarded points on scales that directly reflected differences in weighting, the criteria-based calculation would not be necessary. The root-level rule could use sum_if(x,y,z) to calculate the final grade directly. However, I choose to use a standard scale (0 to 10) to evaluate all criteria and then to assign the weight for the criteria in a separate attribute.

I prefer using multiple attributes for two reasons. First, the standard scale makes grading easier: I know “7” always means 7/10 (and not 7/15 or 7/20). Second and more importantly, having a separate attribute for the weighting allows me to adjust (and experiment with) the relative weighting of my criteria without out having to continually adjust the individual point values of dozens of descriptors. This makes the rubric much easier to adapt for use in new assignments.