Tinderbox Forum

Teaching Tinderbox

We seem to have got off topic, but I thought I would just say that I have never been able to use Tinderbox for a large project. I have wanted to, but it began to feel like a prison and I had to escape. Completely subjective, of course, but I put all my stuff into DEVONthink and use Tinderbox for small, contained projects, and don’t re-use them.

This is an interesting point, Mark, which I understand, though I’m one of the people who would have been helped if I had been told there was a programming language at work in Tinderbox and that one way to understand TB is as like objects with attributes.

I wonder if you could not indicate a middle ground. There are a lot of people who are pretty good with Excel formulas, filters and queries but who are not programmers and do not think of themselves as programmers. Agent queries and simple actions seem to me about the Excel level of difficulty.

Maybe analogising with Excel would help people. I say this because I am in sympathy with the remark made in this (long) discussion that it sometimes helps to tell people up front that this is a task that it going to “take some syntax”.


Addressing your specific question, I’d break what is intrinsically hard about Tinderbox into two phases: before you use it and when you are learning it.

I looked at Tinderbox probably once a year for many years and never quite understood what it “did”. It is hard in retrospect to know what exactly confused me but I think it was talk of agents and that the agents did things for you like filing. That was appealing. But when I tried to find this exact thing, I couldn’t and I didn’t see the building blocks. Sometimes I thought TB was an outliner and sometimes a mind map. Initially I thought the attributes were basically a ludicrously deluxe system for tagging. I read many of the case studies on the site, but they were never detailed enough for me to get it. (I think what I wanted was something like Beck Tench’s videos, maybe Dominique Renaud’s too.)

So, if I’m harsh, when I read that Tinderbox “is a personal content assistant that helps you visualize, analyze, and share your notes, plans, and ideas,” I don’t know what that means. What is a personal content assistant? What is personal content? An assistant is usually a person who helps me by doing tasks for me. It is not obvious how to map those ideas onto the software features described on the website.

Is it intrinsically difficult to describe Tinderbox? Yes, probably. That is why there are so many threads in which someone says Tinderbox is not very good as a such and such type of application, and the chorus comes back it is not such and such type of application, it is a toolbox. That’s not the wrong answer, but there does not seem to be a boilerplate alternative. Instead we get talk of toolboxes and platforms.

If someone knows Hypercard, I tell them TB is like Hypercard and then explain the likeness. Otherwise I start by talking about notes, hierarchies of notes, visualisations of notes, adding date attributes, then visualising in timeline view using those attributes, and then smart adornments, and then try to relate it to some task I think they may undertake.

One way in which the main marketing page for Tinderbox fails, IMHO, is that it does not have the discipline of FAB: give the feature and then the benefit, as concretely as possible. The copy is exciting and promises a lot, but never quite reached me.

My suggestion for a solution in the first instance: run a competition to describe Tinderbox in 300 words or so.

Somehow, I’m not sure why, I decided really to try to use Tinderbox. I do not remember quite what moved me to break through, it may have been something as trivial as the visual overhaul around version 7 (?). I seem to recall that I began by scrupulously following the two tutorials “Getting started with Tinderbox” and “Actions and Dashboards”. (I wish there were a like tutorial for the export template/language.) That made a very big difference. It would be interesting to know how many people really use those tutorials.

Is Tinderbox intrinsically hard to learn to use? If one does those two tutorials rather than read them, in my opinion, no. That is, one can get a basic competence in Tinderbox with an investment of a few hours structured by the tutorials.

On the other hand, without a structured practical application such as in the tutorials, I’d say it probably is hard. That suggests it is not intrinsically hard, but that it requires a short term immersion rather than casual progression. So, by comparison, TB is harder than Excel. You can do a lot of “small” things in Excel without learning about the myriad other things it can do. And you can add a few of those myriad things at a time. It is in this sense atomistic. TB is more holistic.

After basic competence, I think how well you get on with Tinderbox may depend on your background in other areas. If you’re an engineer, that might help. If you’re a programmer, that helps. But being a psychologist or a semiotician might help just as much once you map your concepts to TB’s concepts and understand the toolset. Lots of psychologists use R for statistics (www.r-project.org) but do not consider themselves programmers. It would help though to set expectations for different groups, e.g. this is going to require some special syntax.

For example, I’m still surprised there is no language guide to Action Code from Eastgate. I just expect programming languages to be more or less formally documented. There is atbRef, but it freaks me out that this resource is so essential to the use of TB. (I think, “What if something happens to Mark Anderson?”) (I also worry, “What if something happens to Mark Bernstein?”)

Another thing is that I am not sure that the explanations in Tinderbox documentation are always good ones, because they seem to me too often to eschew analogies with other tools. For example, the TB help first describes an agent this way: “Tinderbox agents scan your document constantly, looking for notes that meet criteria you have specified. When an agent finds a note that meets its criteria, it creates an alias of that note inside the agent.” I would find this very hard to understand if I did not already know about TB agents. Where are these agents? In what way do they “scan” my document? Where do I tell the agents my criteria? The language confuses because there is criteria I “have specified” but then it is “its” criteria that the agent uses. Are they the same? And then, an agent creates an alias to a note “inside” itself. What the hell does that mean? So much is assumed. So much that is weird. It is weird to an outsider that a note can also be a container, i.e. like a folder. It is weird that an agent is also a note.

Roughly, I’d say an agent is a folder containing the results of a saved search. If you want, you can automatically execute some operation on the results of that search. The search results are updated automatically and the operation runs in the background.

I think I understand why Tinderbox documentation is written this way. Tinderbox is a revolutionary tool and it brings with it a different way of conceiving information, structuring it, and using it. There is both a different logical world view and a one-of-a-kind software interface into that world. And there is an intellectual vision behind it, The Tinderbox Way. These things are great and I have learned from them and internalised them. But if the learning curve is to be eased, I’d suggest more use of direct or familiar analogies with other tools and concepts, even if this might seem to make Tinderbox more ordinary.


I really like this analogy. David, you raise a number of great questions. I’ve captured them and will use them in my presentation this Saturday.

Not that I’m intending to dive under a bus, but everything in aTbRef can be recreated from the TBX and the supporting images in less than 5 minutes. Plus if Tinderbox goes but you want the content, the TBX is just XML. That was part of my strategy with the website and why the two zip files are there. Perhaps you’re on a organisation network that doesn’t allow external links (or your government doesn’t). No problem, export the TBX locally on your hard disk, put the images folder in the right place and you are good to go. IIRC, I made the local export controls so they don’t use web-based aspects like Google Translate or Search (if I didn’t that’s still do-able as the templates are very modular).

Sorry, that was slightly off topic, but the gist is aTbRef will likely outlast me. :open_mouth:

I actually wrote (in truth, extended) the aTbRef TBX to learn the nuance of Tinderbox export. Once done it seemed madness to sit on such a private resource. Not least, Eastgate is a small shop: the is no glass-walled building full of marketroids to make cool sell/teach pieces. Bigger outfits don’t have that constraint and so time spend on docs is time away from dev/fixes so I’m happy to help contribute docs.

A gap has been people getting involved in more of the how-tos (far outnumbered by those asking for them!); my input—aTbRef— is a reference and deliberately so, not least because I know how time-consuming making good demos is and doing them as video adds even more time (I live in a busy city centre, I’m lucky to get a quiet 5 minutes without external noise). People recording themselves using Tinderbox is actually also a very valuable resource but the same pre-planning needs are less applicable, though if one’s content is personal of business-confidential it is hard to share.

1 Like

Tinderbox is intrisically hard. I don’t think there is any getting around that but, one of the best pieces of advice I have seen on the forum is to start with just notes and add complexity when it is needed. By complexity I mean, for example, that after some time,

  • you see that some of your notes could be grouped. One way to do that is by coloring them differently, and there you have prototypes.
  • you wish you knew when you’d written a note, and there you have (or at least I did), displayed attributes.

I would have liked to see some example files included, perhaps in an extras folder if not within the application. My preference would be files that illustrate a few related techniques.

Complex DAW applications like Propellerheads Reason include sample song files, which are helpful to view how particular techniques can be achieved. Continuing with Reason, the company’s blog site carries regular posts illustrating a technique or showcasing an instrument. These are usually accompanied by a download containing example files.

So, some examples might be…

  • Here are 5 ways in which you can style the text in your Tinderbox documents.
  • Ever wanted to know how to affect the look of your notes? Here are 5 key attributes you should know.
  • Here are 5 ways in which you can export your data.
  • Etc.

I find these kinds of articles useful because I almost always see, further than what I am being shown, ways in which I can achieve other things. Their value is not only in what they teach me, but also in where they lead me.

1 Like

This is where I am in the TBX learning curve and I completely agree. I actually read The Tinderbox Way as well as the two cited tutorials and frankly, those three resources took me from “this looks cool” to “I can do reasonably great things.” But since the export template/language doesn’t have a Help file, it’s been harder to get started on that!

There’s a big chapter in Tinderbox help. Just saying…


On the latter note, in app Help go to Export -> Export Templates to find that content.

1 Like

Bingo. And the same is true of lots of other applications.

It is not true of most programming languages.

This was my breakthrough; for me though I think it is “short-term immersion with a purpose.” Just playing with it for playing with it sake can be fun, but I find that I learn faster and retain the material better when I have a specific problem to solve. It is much more rewarding at the end of the immersion when there is a tangible asset to show for the effort.

Here is the rub. When you have a problem to solve you’re probably on the clock, which means that you may have a tendency to get frustrated and quick before you make your breakthrough in using Tinderbox because you need to get your project done. There is a balance here. I find that I need to draw on that internal grit to push a little harder, did a few inches deeper, to get to the diamonds.