Tinderbox Forum

Teaching Tinderbox

In another thread, @Haberjr recently raised the question of “Tinderbox’s learning curve”. Is Tinderbox hard to learn? Why?

I’d like to distinguish three kinds of difficulty:

  1. Some things are hard. That can’t be helped.

I distinctly remember how hard it was to learn to read, in part (I suppose) because I was, at first, particularly bad at it. Reading is hard! It takes most people months or years to master.

  1. Some things are hard because they’re unfamiliar to some new Tinderbox users, even though they’re familiar to others.

For example, the general meaning of the expression $Color(parent)="red" is likely to be evident to users who have a semester of computer science, or equivalent experience. You can guess what the quotation marks mean, for example, by analogy to C or Java or Scheme or whatever else you used in school. If you’ve never tried programming at all, though, it would be less clear what this means.

In cases like this, we can help but we can’t make the complexity vanish entirely. Tinderbox uses a number of important ideas that emerged over the first generations of computing, and if those ideas are new to you, they’re new. The good news is, they’re worth learning! But some difficulty may be anticipated, just as you’d expect a certain degree of difficulty commencing work in an unfamiliar area.

  1. Some things are hard because Tinderbox explains them poorly.

For example, until recently the main Tinderbox window had two adjacent buttons, both labelled “+”. One added tabs to the tab bar; the other added attributes to the displayed attributes table. This wasn’t idiotic: both buttons are adding things, and each is clearly placed within its own visual context. Each had an explanatory tooltip. Still: two buttons with very similar labels, quite close to each other.

This was, as it happens, not easy for me to see. In the development environment, those two buttons lie in completely different files, in different parts of the program. I know what each of them does. As a result, the possibility of confusing one with the other was not apparent!

So: what’s intrinsically hard? What are challenges that could be addressed with better demonstrations or more ample illustrations? What confusions could be reduced through different labels or new gestures?

1 Like

I’m not a new Tinderbox user, but I may have some insights here.

The Blank Canvas

When you open TBX for the first time, you get a blank canvas with instructions to double-click to create a new note. That’s it. This isn’t inappropriate at all, but it is intimidating in the context of TBX’s rumored power. You wonder where to even start…you wonder how to get to what you see online, even the screenshots on Eastgate’s website. One easy fix here is to just include an official “starter file” with every build. Even better would be a starter file with basic prototypes already added AND a separate “sample” file, maybe something like the recent Zettelkasten test documents I’ve seen here. Either way, because many people can learn much more effectively by example, this would be a great way to start people on the TBX learning curve.

The Coder Problem

Personally I think Roam Research is actually more guilty of this, but it’s elementary to say that TBX comes alive when you start to fiddle with the power of agents and other TBX coding. The problem here is that many users do not have any kind of CS background, making it difficult–again–to know where to start. The Help function is important here, as are examples and starter files as above. I think even more useful would be videos that show simple use cases for why you’d want to really dig into TBX’s coding powers.

The What Do I Do With This Problem

This probably is a restatement of The Blank Canvas problem, but I’m listing it separately because I think it should be considered its own (very solvable) problem. It’s also why so many clamor for videos. In this case, TBX isn’t that different from Notion.so. Both apps are blank canvases and while Notion tries to mostly hide the coding from the user, it’s actually remarkably similar to TBX in many ways. The difference is that Notion has a lot of use-case videos and that helps people figure out how the tool can be useful to them.

And finally…

The Optimizer’s Dilemma Problem

I just made this up, but basically, people will want to know the “best” way to use Tinderbox. Of course, that’s an unanswerable question, but most folks won’t be ready for that answer right away. Examples of what this looks: “Do you keep everything in one giant TBX file or do you have multiple TBX files divided by topic or area of responsibility?” or “Should I view this primarily as an outliner or primarily as a mind-map?” (A question that only a new user would ask.) or (and this is STILL one of my issues) “How can I get this stuff out of TBX now that I’ve put it in there?”

Okay time to get to work, but I hope this is helpful!


I think these can be the same Tinderbox document. I suggest it’s better to focus on a “sample” file, and in the sample point out how to find and use the features that one can create or add-in (in the case of built-in prototypes and templates. A few existing cases where these sample / starters exist quite well, in my opinion.

  1. Curio’s built-in help documentation is made as a Curio document. Users can save their own copy and annotate it for their own private uses. Why isn’t Tinderbox Help a Tinderbox document that we can edit and expand on for our own users? And that also includes living examples of how Tinderbox works.

  2. TheBrain includes a “Create a Quick-Start Brain” that creates a sample database that new users can play with and see all the key features of the software at work. I can hear the caveat now: “But a sample, or a starter document will fit one person and not someone else.” Yes, true. So what? A starter document is better than a blank page. —

Disclaimer: I am merely a Tinderbox user, have nothing to do with Eastgate, and only volunteer my own and no one else’s opinions. What I suggest may or may not be relevant or work. Don’t shoot.

1 Like

Ahem, the Tinderbox Help is written in Tinderbox (I know as I’m partly to blame for it). It provides the Mac Help for the app and is set up (using a few externals command line tools) to make a PDF version. Even without the extra tools it creates the Help content as a single, styled, HTML page with linked images.

Starter files. Ahem, again, the forum has offered such a file for some while, though I think some test/tune is needed to make it better for complete novices.

There is also the now unloved Tinderbox Cookbook which is also made from a Tinderbox file.

Whilst the Map is Tinderbox’s star view, I think it leads people to get lost. it’s easy to add a few things, but difficult to leverage out from that. Plus, experienced user learns it’s not ideal to make a root level map (which the current default unintentionally encourages.)

I’m actually leery about giving new users use-case templates. Experience suggests it just means they (a) often think this is what Tinderbox does (i.e. little/nothing else) and that as some function is built-in, any small change has to be done for them by the community. I’m in the (minority) who wants to see a more Engelbartian bootstrapping approach where people learn the tool so as to use it better. Then again, inquisitiveness isn’t a common trait so perhaps that’s an over-optimistic aim.

1 Like

My point is that the Tinderbox version of Help and the starter file are not easily discoverable. The examples I gave from other applications are cases where the files are put right in front of users, in their native formats, so that the users can see at once excellent examples of what can be done with the software.

Why can’t there be a command in the Help menu that users could click to grab copies of a Tinderbox .tbx versions Help and the starter file and start working with them?

Worrying about whether users will misunderstand samples or starter files or use cases – or whatever – results in a kind of paralysis that I think is at the root of the round after round after round of discussions here where we see frustrated users who honestly want to know “how do I get started”.


Yea, I would definitely not worry about how users will understand or misunderstand starter files or use cases. It’s far more valuable to get those starter files and use cases out there so people can get going. Again, people who are curious do best learning by example. This is the classic problem with Help files and manuals in general. Let’s face it, “our tribe” is not likely to RTFM…the desire to jump in and start tinkering and “learn by using” is strong in us. Having an example file to learn from is must more useful to me than Help. Help is where I go when I know what I want to do, I just need to learn how.

Key Insight I Just Had

The problem that people have isn’t learning how, it’s knowing what to do. Help and documentation are crucial for the former but rarely informative for the latter. Videos, starter files, and robust sample documents are ideal for the latter.

That starter file should just be packaged with Tinderbox and load up on launch. That alone would help so many people get started!

No disagreement here! Quite agree re discoverability. In terms of knowing what to do it might be more useful to rather than show, for example, a finished zettelkasten-type file to instead show the techniques you will need to make such a file. Teach a person to fish rather than simply giving them fish.

Agreed. I just think there’s an extra step with Tinderbox. “To fish” is a basic concept. “To Tinderbox” is not. A good example is the other thread where the gentleman is asking how to create a dashboard for doctors and scheduling. Once the use case is there, there are many ways to help him get there. But, for example, it wouldn’t have occurred to me to use Tinderbox for that at all.

So we have two issues: we need to define the verb and then teach that!

1 Like

Another pinch point I’ve noticed is an itial burst of exploration resulting in a mass of note-level OnAdds/Rules, Displayed Attributes, and a discrete agent for every signle task. At this point people would benefit from:

  • conditional actions
  • prototype based inheritance (change on thing not many
  • considering when to make rules into edicts
  • stamps for once-only tasks
  • controlling agents (use of and priority), and constructing good queries

My previous reference to the Cookbook was the thought that we might re-cycle some of the ‘tests’ as code samples. The method of using HTML export and javascript to test cookbooks results proved to have its challenges but I think there are lots of code samples that we could make more accessible to more users.

1 Like

In my experience, retrospectively, Tinderbox worked for me in a similar way than one can experience when you switch from a scholar writing habit to a free form narration. In this latter case, you experience that the only thing you have to do if you really want to progress consists in writing and discovering your own inspiration, your own ability to write literature. For instance, Pierre Boulle, a french writer who created the universe of the planet of the apes, wrote something about the path he had to go through when he was writing La planète des singes. He said that he discovered the main theme of his book writing a narration. There’s there a virtu of gerund which, in my experience, applies to Tinderbox. You discover what kind of usage you could do while exploring Tinderbox and the more you try it the more you’re familiar with. It requires thinking while most of digital writing tools give us a ready to use tool which dispenses partly to think what we could do with since we cannot do anymore than what the tool has been designed for. There’s there a relation to people and world which could be taught and deserves to be experienced : this is the way I use that tool: watch me using it and find your way to use it and I’ll watch you using it too and I’ll learn from you.


Not only that, but the Tinderbox Help file is enormous. It might work as a demonstration of advanced Tbx usage, but is completely unsuitable as a tutorial for beginners.

For beginners, I would recommend a “quick start” Tinderbox small enough to work within the limits of the free trial. It can include jumping off points to the full documentation, but shouldn’t require the full documentation to be useful.

I can’t disagree with anything from what I read above.

Ok, where to I start.

What I’ve learned is that Tinderbox is a thinking tool. It helps you collect, curate, compose, and contribute (the 4 Cs). There are sub-element here, e.g. connection is part of curate. To successfully use tinderbox you need to be able to put yourself in the right mindset for each of the four Cs and trust that Tinderbox and the community will help you glean insights, learn and get to the end as you grow and explore you thoughts, mind and notes. Tinderbox becomes an external brain.

It does take work, however. It is am muscle. You need to be willing to reshape your thinking and how you approach problems and what you want to accomplish. You need patience. You need to be willing to look at your problems from different angle, and be willing to approach them in different ways than you would initially expect. In other words, you need to approach Tinderbox with a beginners mind.

Tinderbox is a lot like Yoga. It is there for everyone. No matter what level of fitness you have
you can benefit from its its use. All the lessons are there. They have been forever. Some will be able to touch their toes immediately,while others not yet or may never be able to do, but the benefit of going through the practice is in itself useful.

Now, having said all this, I also agree that the best way to approach Tinderbox is through simple use cases and examples that are explained through video and with documented notes. It starts with,

Release fear,


  • what a note is
  • what an attribute is
  • that all attributes are associated with every note
  • that user can create attributes
  • views provide differentiated visualization of notes
  • that notes can be linked and liking can create insights and exchange data
  • that you CAN get your data out of Tinderbox and pretty it up in another application for publication
  • that your notes can be anywhere in your file and you can use agents to discover them and manipulate them as needed
  • that the vast majority of Tinderbox documentation assumes a lot of knowledge and that you can use the community to fill gaps
  • that you need to read, re-read, and experiment with the example in the reference file

Again, all of this is best shown through example. A few of us are working on videos right now and sample files now. We hope to be publishing our first ones soon. The first few are pretty rough, but their getting better.


As one of those users, emphatically YES.

Programmers, no matter where they ultimately end up, start off by writing “Hello world” and dinky little sort algorithms. Artists start by painting color wheels and sketching boxes with shadows. Pianists do finger exercises.

What is the equivalent for Tinderbox? It’s all well and good to ask people to be inquisitive, but someone who can’t figure out how to manage a to do list or an address book isn’t going to turn to Tinderbox when they need to plan a novel or a research program.


Thinking about using Tinderbox, I’m wondering if we can come up with a list of desired and prioritized skills sets needed to be successful with it, for example:

  1. Writing (both short-form and long-form)
  2. Process of thinking and use of results from it - collection, curation (inc. connection), composition, and contribution.
  3. Vulnerability and collaboration, to get the most out of Tinderbox you need to be vulnerable–mostly with yourself, let your ideas become, let it be messy at first, accept that you don’t know all the pieces all at mone, trust it will come–and collaboration (get help from the community–not just with Tinderbox, but with your ideas).
  4. Organization (structured and unstructured)
  5. Understanding the relationship between an object (i.e. note) and associations about this note (i.e. attributes)
  6. Basic HTML
  7. Basic query language structure (need for precision)
  8. Problem definition (ability to clearly articulate what your end game is)
  9. Patience (with yourself and the tool)
  10. Beginners mind (ability to let go of the past and pre-conceived nations an accept the present for what it is, revel in the joy of the now)
  11. (all good lists to 11) - let go of fear

NOTE: Most of these items have little to do with Tinderbox and everything to do with general knowledge. Google did an exhaustive study on what it takes to succeed at Google a while back; guess what, technical skills were nowhere near the top, thinking and human skills, communication and problem-solving skills made the top of the list. I think we’ll probably find similar results with being successful with Tinderbox.

Are there others?

One note I’d like to call out, much of the Tinderbox documentation and the examples in the forum are incomplete, not out of negligence but out of contextual errors and undocumented assumed knowledge. This has been one of the hardest things for me to overcome with the forum. When I look at an “example,” there are often missing pieces and steps to the formula and the threads because there is a lot of assumed knowledge; this is perfectly fine once you’re onboarded into the flow, but it is tough when you’re trying to get up to speed.

For me, interfacing with the Tinderbox forum is a lot like trying to dock with the space station. To do so without totally missing the dock or killing myself, both the spaceship (me) and the space station (Tinderbox) need to be at the same relative speed. Once they’re up to the same speed, all is good in this world; I feel like I belong and can figure it out, that I’m in sync. That is not saying all is easy because thinking and growth are not easy, but it is certainly a lot more fun and easier to be present.

Another analogy is a cookbook, the “recipes” and list of ingredients for getting stuff done in Tinderbox are all over the place. There have been attempts at creating concise recipes and ingredient lists, but I think these still lack formulaic rigor; again, there are Tinderbox recipes and cookbooks, but so many are lacking subject matter expertise, e.g. cookbook for research, cookbook for time management, cookbook for sales pipeline management, cookbook for industry analysis, cookbooks for different styles of cooking (e.g. French vs. Jamaican). I, and some fellow Tinderboxers, are working on coming up with something like this.

So, for me, the questions are:

  1. What are the basic skill sets needed to be successful with Tinderbox?
  2. How do we help people get up to speed, i.e. create lesson plans that scaffold them from where they are to where they want to be?

@satikusala , I think those are very interesting and helpful thoughts.

But it might be like boiling the ocean.

Is Eastgate in the business of teaching customers skills that are not directly part of using the product? Is that the purpose of this (or any) forum? I’d suggest the forum exists to explain and help users how to use the software. Just the software. If the reader doesn’t know how to think (doubtful) then, well, that’s that.

As far as “incompleteness goes” – sure. That’s always the case with any kind of technical help or manual. Silly example – but if someone asks “how do I make bold face text”, do they need to be dragged all the way through how text gets entered, edited, styled, etc.? Of tell them “use Format > Font > Bold or press ⌘B with the text selected.”

Of your list, these are the only ones where Eastgate’s assistance is relevant or wanted.

The others are certainly valuable, but it’s patronizing to assume that users don’t already have them (or at least a process for working on them), and presumptuous to suggest that the Eastgate forum should be involved in developing them.

Your cookbook analogy is also relevant here. Some cookbooks are aimed at people who’ve never seen a kitchen before, and have step by step instructions for such basic tasks as peeling and chopping an onion. Some just say “caramelize 1 cup onion before adding to beef broth.”

1 Like

Yup, don’t disagree with you at all on this point.

As for being “patronizing,” that was not my intention, was more of a generic list of skills and was not intended to suggest who would deliver them.

1 Like