Teaching Tinderbox

Yes, I’ve done that, and people have indeed been very helpful. Which I appreciate.

But a major source of frustration is that I find myself repeatedly needing to ask about what seem like they should be very basic tasks. To use the chess analogy upthread, I feel like I’m asking how the horsies move, not how to draw a minor piece endgame.

Life is short and full of learning opportunities. We appear to disagree about where “learning how to use Tinderbox” should be on that list.

Yeah, after, what 13 or 14 years using Tinderbox, hundreds of documents made, hours spent here trying to give a little advice, I find that every time I get into building something more than a modestly complicated document I have to go crawling through aTbRef to figure out how something is supposed to work. Export code knocks me down every time I build templates.

I don’t know that that’s necessarily a bad thing – it’s certainly not what I experience with most software. And I’ve been an IT professional and executive for four+ decades, so I wonder if I should know better.

Everything works out in the end and I’m self-sufficient for the most part. But I’ve had my share of trying to screw in nails or hammer in screws with Tinderbox.

1 Like

This is illuminating as it runs counter to the narrative thus far. think, in context, “how the horsies move” is actually well covered but I’d quite agree that dependent on your POV/vernacular/field/whatever, that resource might be difficult to find and when found may not make immediate sense for reasons unguessable to the resource author. I’d like to think all the ‘regulars’ here would thinks that’s something to fix, but may be unclear how to do so for lack of clear indications to how existing resource fails. That was the nature of my point about ‘throwing stones’. In pain we tend to forget that the cause for our pain isn’t immediately obvious.

The biggest lesson by far of the 15+ years I’ve written and maintained aTbRef is the ways in which stuff I thought was clear doesn’t make sense to the reader. Perhaps against expectation, this is an experience I fully take to heart and unseen by readers many parts of that resource are re-written or re-linked to reflect hitherto un-guessable insights mailed in by readers, but enabled by people taken a few extra words to explain the disconnect. As one who’s technical expertise draws mainly on the kindness of strangers, I’m unembarrassed to state I want to help other.

So how does this apply to documentation as a whole (given that I’m aTbRef’s author as it’s my personal initiative)? I think we’re all too ready to complain: we state our dissatisfaction yet omit to explain with what we are dissatisfied. Often, these problems are narrow (scopable) and fixable. Where not so, having a contextual description it is also the bedrock to productive debate towards a solution.

The hard part with a toolbox (Erector™ set) is to remember that we are just using one tool really hard, and we might be the only person with that exact use. In part, we don’t do so as we’re ‘smart’ so clearly other ‘smart’ folk must do the same? It’s human fallibility.

Going back to may earlier observation I’d encourage people to simply articulate, without attitude, what they can’t find/understand—or where they get lost. If documentation—vendor or volunteer—is sub-par please understand it is not because the authors’ don’t care.

.In a user-to-user forum, as fellow users we don’t control the app, but can help with its use.

The thread @satikusala linked to is a good case in point. By taking a moment to explain a problem:

  • we got a solution
  • the solution was a kludge (as I discovered a functional limitation)
    *as importantly leading to:
    • a feature request to update ^text^ functionality
    • c.20+ pages in aTbref were edited with improved/data links as a result.

Sorry if I appear a booster for user forums. But with a helpful community, help really is a just post away. I can’t feel otherwise—I’ve learned so much by the kindness of strangers.

@kderbyshire First, thanks for the really engaging back and forth. I must admit through, through the exchange I’ve lost sight of the specific project you’re looking to work on with Tinderbox. Do you think we can go back to that?

Here are a couple of questions:

  • What do you want to do? Get done?
  • What inputs do you have?
  • How do you want to curate these inputs?
  • What insight do you want to draw from these inputs?
  • What outputs are you looking to create from these insights?

I’d love to take a stab at building a sample TBX for you.

Michael

That makes me feel both better and worse.

This thread from last year outlines my workflow and a first cut at tackling it via Tinderbox:

Since then, I’ve tried the same approach with other projects, with mixed results. Creating a Tinderbox Map view to help me see patterns in research materials works really well. Attempting to convert that view back to a linear outline – either in Tinderbox or another tool – that I can use as a starting point for a draft often leaves me wondering why I don’t just use Post-It notes.

(And it doesn’t help that I tend to have more time to putter on the front end – organizing material – than on the back end, when I’m ready to start writing.)

1 Like

Ok, I think I understand. I’ve been meaning to templatize my process for what I think i a similar workflow:

  1. Read stuff
  2. Capture and cite notes (quote, stats, ideas, etc.) in Tinderbox, link said note to DevonThink original source
  3. Generate my own note and thinking that come out of #2
  4. Curate insight - make connection, use maps, outline, chart, agents, etc. to make sense of the data
    …run out of time
  5. Pull together and publish the article I wanted to release
  6. Lather, repeat, rinse.

Please let me know if I have these steps generally right.

The beauty of Tinderbox is that if you do this work in one more more Tinderboxes you’ll find that over time you’ll have started to build a knowledge/asset database that you can draw upon for future work.

Again, I’ve been meaning to pull my process together for some weeks (@wajakob asked me for it). Give me until the end of the week and I’ll put something together. I’ll record it and also will present it at next Saturday’s meetup (@Sylvaticus).

1 Like

Close. My process is more like:

  1. Read stuff.
  2. Capture notes in Scrivener, linked to original sources in DevonThink.
  3. Export from Scrivener to Tinderbox, split into bite-sized chunks, retaining links to original sources.
  4. Shuffle chunks around in Tinderbox Map view, forming clusters of related ideas.
  5. Write short topical summaries based on those clusters.
  6. (Attempt to facilitate 4 and 5 by assigning topic-based tags in Tinderbox, and using those as a tool to get more structure in Tinderbox and export the results back to Scrivener. Curse a lot. Run out of time. Resort to copy and paste. Curse some more.)
  7. Write draft in Scrivener. Revise.
  8. Go back to the original notes in Scrivener or Tinderbox to double check sources. Wish I hadn’t wasted so much time in step 6.
  9. Publish. Wonder if inserting Tinderbox in the process was worth the bother.
1 Like

Doesn’t look like it is. You have a lot of software involved in what’s just a vanilla standard read, take notes, consolidate, composition cycle.

Here’s where the key benefit might lie — assuming steps 4-6 are substantial and protracted. If they’re just pro forma or due diligence, then there’s not much to be done here! But if 4-6 takes time as you gather new sources and gain understanding, Tinderbox can provide a really nice framework for an evolving body of knowledge.

2 Likes

Well, the reason why I keep coming back to Tinderbox is because I’m not entirely happy with the way the process works without it, either. Thinking is hard.

Much depends on scale. I don’t need Tinderbox (or much of anything, really) to organize a 500 word news brief. I would like to be able to use it for much larger projects, but am reluctant to do so at my current level of fluency.

3 Likes

Steps 4-6 are very much where the brain work lies. If you write out the steps, the same basic flow applies to a 500 word news brief as to a 100,000 word book, but clearly the difference between the two is more than just volume.

1 Like

Suggestion: use Tinderbox as a sidecar, playing a small role in a large project. If you get stuck, there are lots of people who can help, but worst case, it’s a small role!

1 Like

Going back to the original topic of the thread, it looks like I’m describing a pretty common task. As @PaulWalters put it, a “standard read, take notes, consolidate, composition cycle.” So resources that help with that cycle might be useful to more users than just me. To that end, here are the specific Tinderbox tasks that I found myself needing to accomplish:

  1. Import existing notes. Assign $Source attributes.
  2. Explode notes, assigning the same attributes to the children.
  3. (Map View) Cluster notes topically. Topics are emergent, in that I don’t know what they are until I’ve reviewed the material.
  4. (Map View) Use Adornments to visually distinguish clusters and individual notes, as needed.
    – At any point, create new notes with my own observations or incorporating additional research. Add these to topical clusters.
  5. Assign $Tag attributes relevant to each cluster.
  6. (Attribute Browser) Within each cluster, develop narrative order. Highlight or create notes reflecting the central theme of each cluster.
  7. (Attribute Browser) Determine overall narrative flow between clusters. Assign attributes accordingly. (First, Second, etc.).
  8. Export the “highlight” notes in narrative order, thereby creating a draft outline.
1 Like

@kderbyshire. Thanks for sharing your process. Couple more questions.

How long are your articles? (word count)
Do they include images?
What do you use to manage your references? Citations?

I too love Scrivener, especially for long-form content, but you can actually accomplish everything you’re doing above with Tinderbox and DevonThink, you may not need Scrivener to publish (especially for short-form content).

I completely agree with @eastgate above RE “Tinderbox can provide a really nice framework for an evolving body of knowledge.” That is what I meant when I said “Tinderboxes you’ll find that over time you’ll have started to build a knowledge/asset database that you can draw upon for future work.”

I’ll pull together an example of this later week. To make my effort more practical, can you provide an example of three public source articles? I can review them and attempt to make an article out of them. If not, I’ll use my own.

Lol. No. Leaving the relative merits of the two applications aside, Scrivener for iPad is one of my most-used tools. Also, I need to be able to get material out of Tinderbox without cursing first.

For the rest, I made a new thread, here:

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”.

3 Likes

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.

5 Likes

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.