Tinderbox Forum

Getting Started on the Right Foot

I am a brand-new Tinderbox user, just licensed it today and am jumping in with both feet. My current need is for a personal knowledge base. I am a freelance software developer, involved in a lot of projects, with numerous clients. I am looking for an elegant way to track all the various pieces of information that flow in, and how they relate to clients, projects, tasks, etc.

The first thing I am running in to is a question regarding the usage of notes and links vs attributes. For example, I could create a Client prototype, and then create one note per client based upon that prototype. Then I could create a Project prototype, then create one note per project based upon that prototype. I could then create links between the projects and the clients. Alternatively I could put projects underneath clients in a hierarchy. Another alternative would be to do away with Clients altogether, and just use the Organization attribute on the Project prototype and write the name of the client in there instead. Anyways, hopefully you know where I am going with this…

I guess what I am running into is a lack of understanding as to which organizational scheme will serve me best. How does one know when to use hierarchy vs links to represent relationships between notes? When does it make sense to have data as an attribute vs making another note?



Have you read Mark’s “The Tinderbox Way”? It’s a good starting point.

There is no best way. But I’d suggest not thinking of Tinderbox as a hierarchical tool. Finding and exploring relationships between notes, such as with links, is the power of Tinderbox.

Attributes are frequently characteristics common to multiple notes. Characteristics can have different values. Think of color or height. Or whatever attributes you want to imagine.

Don’t race into complex projects with Tinderbox. Start with a small project you already have done in some other medium, and replicate it in Tinderbox, and see how Tinderbox might give a different approach on doing that project – perhaps an article, or a work or personal plan.


I endorse the last post (to avoid repeating it!). I’d analyse your meaning of ‘best’ - what do you (as opposed to others you assume are doing similar task) want from your data. Consider that attributes - or rather attribute values - can be thought of as proxy links. Explicit links are of most use in Map view, as it is the only one that fully displays them (edge case - Timeline can too). Maps (but not timelines) show a single container’s context and as such aren’t good if you want to lay out data hierarchically.

Expressing every connection as a link can lead to very messy maps, though you can toggle visibility of links (at per link type scope). You can query your data via links (e.g. via linkedTo() and similar actions). However, attribute values are easily queried so value sets (query matches) are implicit links and can even be turned into actual links if desired. Which leads to the point that…

A strength of Tinderbox is is allows incremental formalisation, so you don’t have to decide all structure from the get go or be forced to use someone else’s structure that never quite fits your own use. Inheritance and prototyping are nicely and flexibly implemented.

So, as @PaulWalters suggests, do small experiments and adopt successful ideas into your actual ‘work’ documents. It may seem more work at outset but it pays off quickly, and as your familiarity with Tinderbox grows the fewer external tests you’ll need to run. Apple’s versioning is built-in to the app. Add in Time Machine and other methods of your choice there’s usually as short cope roll-back if you mess up and need to step back a stage.

1 Like

What @mwra said.

Adding: links are important in maps, but are also invaluable in the text (i.e., the the value of the $Text) in your notes. There are a number of ways to use links in your text to connect a thought in one note to another note or notes, even to specific blocks of text in another note.

Tinderbox 7 has a wonderful new Quick Links feature**. If you want to link your note “My future” to your note “Gold mining will make me Croesus!!”, merely start typing [[G in the text of “My future” and you’ll be offered a popup menu to link to “Diamond mining”. Very similar to wiki linking. And of course your text can link to any web site with web hyperlinks added to your rich text.

Final note, before we get you too impacted with information – there are numerous tutorials available in this forum, in the legacy Tinderbox forum, and from bloggers such as Steve Zeoli.

** Mark Anderson will never say it bluntly, but his always-up-to-date aTbRef is the most comprehensive user-contributed documentation for any Mac program you will find, IMO. Use it often!


A couple of observations on Tinderbox projects, in the language of the software world:

  • The Agile movement advocates trying “the simplest thing that could possibly work.” That works well when starting new Tinderbox projects. It’s better to leap in and build up some notes, even if they’re not organized very well, than to build a large but empty formal structure.

  • Tinderbox makes refactoring fairly straightforward. This is a deliberate contrast to databases, where getting the architecture correct from the outset is important.

  • Deep hierarchies tend to be hard to maintain.

  • Tinderbox 7.0.1 introduces a new way to represent object composition. I think it will prove powerful, but it’s new, novel, and not very thoroughly understood.

  • Links are 1:1 and always have a referent. That’s sometimes a guarantee you want. If you make a link to a Client note, that link will survive things like changing the name of the client. If the client is deleted, the link will be deleted too. This isn’t something you need often, but when you do need it, you really need it.

  • Tinderbox automation is easier when working with attribute values. It’s easier to assign a value than to make a link.

  • Don’t overlook Attribute Browser. It’s a clumsy name for a very useful tool.

This is a response to the original poster, Damien, but I’m referring to points in the Eastgate / Mark B post just above.

I wanted to say to Damien that all of the advice you’re getting here is sound. But my own experience with the program (over now nearly a decade, after previous immersion in the sublime DOS program Lotus Agenda, and then the Windows program Zoot), makes me especially want to emphasize the points I am quoting above:

  • My natural instinct was to build hierarchies, based on a long reliance on outlines for thinking and planning. In Tinderbox, associations of various sorts generally pay off better than hierarchies, for me. These associations have several forms: links on a map (which I rely on relatively little); physical arrangement of items on a map, especially relative to adornments (which I use more); and categorizations of items via attributes (which I use all day every day, for everything I do). You can tag, classify, identify, and otherwise meta-tag your info practically any way you want through attributes, and you can flexibly add or change anything as needs adjust. Main point: I find TB most powerful as an associative rather than a hierarchical tool. (This is related to Mark B’s first two points.)

  • I can’t say enough about the Attribute Browser, which is an awkward-sounding name for a very powerful tool. Simplest example: suppose one of your attributes is $City (attributes begin with $, by convention.) And you’re entering info about places you want to go or places you’ve been, with a $City tag – Paris, Sacramento, Dubuque, whatever. When you switch to the Att Br view, it shows everything neatly classified by city. This is something that the old forebears like Agenda and Zoot had done all along, and its addition to TB a couple of years ago was transformative for me.

I agree with the other advice too: start with the simplest structure that will work, add to and adjust it as you like, learn by going and doing.

Also be aware that, compared with products from big companies, Tinderbox will sometimes crash. I think that’s because it’s evolving and being refined continually–literally hundreds of incremental releases in the time I’ve been using it. But I can’t remember any case in which I suffered any data loss from a crash – 99% of the time you restart the program and all is well. And if you send the crash log to Eastgate, 99% of the time the problem will be addressed very quickly in an update or release.

Have fun.

Update to add that all the suggestions above, from the two Marks and Paul W, ring true to my experience. Also the invaluable aTbRef is the first place to go if you’re wondering, “What does this command do?” or “How do I try to get the program to do this particular thing?” And all of the tutorial videos, from a range of perspectives, are cumulatively very helpful. Questions asked here tend to get answered fairly quickly.

But start simple and learn by growing and expanding.


Thank you for all of your help and suggestions. aTbRef is a fantastic reference. Half of the battle of using the documentation for me is learning the lingo for the various parts of the software. Once I know what it is I am actually looking for, reading the documentation becomes easier.

As per some of what I am reading above, I am continuing to play with the software and try a few things. I am finding as I go that keeping the hierarchy relatively flat and using attributes and links seems to be working out better for me than grouping things by hierarchy.

Interestingly, I am finding links really useful in the “roadmap” pop-up view. If I have a phone conversation with a client, and we talk about a wide variety of things, I can record that conversation in a note, then link it to various projects/tasks for future reference. Then if I am looking at the project, I can see all of the conversations I had about that project, or if I am on a task, I can see what conversation was responsible for initiating it.

Using it this way, I am going to have links all over the place. This might not look great in map view, but I am finding myself not really using that much at the moment, as I seem to gravitate to outline view the most.

I am finding myself wishing I could display a particular outgoing link destination as a key attribute on notes. Is such a thing possible? Right now to achieve such a thing, I have created a string attribute and then an agent that looks for a particular link type, and if it finds it, puts the name of the link destination into that attribute. Is that the best way to achieve that?

1 Like

What is ‘particular’ about the link? Unless it has some defining condition or metadata, it’s hard to identify except by eye. It’s also nor quite clear what you’re actually trying to achieve. It seems like the problem is you want to be able to follow a basic (note-level, not in-text) link via a Key Attributes entry. The latter isn’t possible, though you can - as you are - store the name of the note as a string value.

Anyway, it might be easier to help with a bit more explanation of the desired outcome and the data available. Whilst it might not be possible in the way first intuited, there is often a workable alternative once the use case is clear. If you want to follow up of this it might make sense to start a new thread on that particular task.

I understand the point on terminology but it’s the same from both ends as different people have different assumed terminology so it’s hard to guess what mapping of terms is desirable in aTbRef. What sort of terms where you looking for, and in what context? As aTbRef’s written as a community resource I am (as its author) open to suggestion. What terminology needs more explaining, and where should such descriptions live within the hypertext as a whole?

I can second the Mark’s caution against deep hierarchies. If you’re used to outlining, it’s a real temptation to use hierarchy when as noted labels as attributes work much better. Similarly links are cool, but topics as attributes work better.

I’m really liking composites as an easy way to group without hierarchies. I was always searching for a better way to group notes on a book than making a container. In Map view, it’s great to have all of the chapter notes on a book right their, compact with a separate not for the source. I love how the composite creates a text view where all of the chapter notes can be browsed in a single window.

At this point I use links very deliberately. Like in a summary note where links act like references to footnotes. I can create a metanote about a subject that links to the books or papers referenced. The Devon Think integration finally makes it possible to keep the PDFs out of the Tinderbox document with a simple link out to the PDF.

1 Like

Perhaps if you are doing something very structured, like a book, then attributes are a better way to go. However, for doing daily work, I need more ad-hoc relationships, and thus links feel like a more natural fit.

For example… say I have a phone call with a client, and I write a note as we talk as a record of the conversation. In that conversation we may talk about a couple different projects, and the may also generate multiple tasks that I need to do.

At the end of the conversation, I can create a relationship between the conversation and the person using a link. I can also create a relationship between the note and project(s) we talked about using links. Additionally, I can create relationships between the tasks and the conversation using links. Links seem like a natural fit for this kind of thing.

Now that I have all those links, I can use the roadmap feature to:

  • Look at the Person, and see all of the past conversations I had with them.
  • Look at the Project, and see all of the past conversations I had about that project.
  • Look at a task and see what conversation it was related to, and get clarification if required.

The roadmap feature lets me quickly follow trains of thought through projects, conversations, and tasks. It seems like this would be more difficult to do with attributes. Perhaps I am wrong though, I am willing to be enlightened :slight_smile:

1 Like

Using links instead of containers is interesting to me…

Maybe it doesn’t matter, but which way do the links go? Let’s say I make a note to represent a project - now I make another note about the project. Which way do you link it? And does it matter?

I have been linking back from the note to the project, with an about type or something similar. I don’t know that it actually matters which direction you go, but it feels more natural to be working on the note, then drag it’s link to the parking space, and then go find the project it belongs to.

Yeah that makes sense to me. Mainly cause it’s much faster than doing it the other way :slight_smile: But conceptually, a project note would exist without any of those related notes, so it doesn’t need to “know” about them directly (obviously you can find them via its inbound links). Whereas these “about” notes exist in relation to the project, so we define the relation on them.

I think this wants consideration with respect to scale as the doc grows. Roadmap is a neat feature but there are some gotchas to bear in mind. If you want list selections to follow (text) pane focus you can only do this if the view is as a pop-up, but not when torn-off. In pop-up form the text labels are necessarily short/elided thus it may be harder than imagined (with real-world data) to tell from the view alone as to what the list item is as the unique part of the label may not be visible.

I’m not advising against, but rather suggesting doing some actual hands-on testing before committing as the view is something the user can’t alter - unlike their data structure. I’d make some notes with the sorts of (display) names you’ll give them and link them up and see if Roadmap gives you the clarity of view assumed. I hope it does, but experience says to check first.

I really appreciate your feedback here. After using links in this fashion for a couple weeks now, I appreciate the power I have to form ad-hoc connections between notes. They are less than ideal for displaying though, as those views (as you described) are somewhat limited.

I am at a loss at the moment as to how I might achieve achieve similar results using attributes.

To continue the last thought… I had originally started using hierarchy for some of these relationships, but earlier in this thread I was advised against relying on hierarchy too much and to keep things flat.

I do think it’s worth spending some time getting to know Attribute Browser. Any attribute can be inspected and you don’t need to to have an AB view tab (or tabs) open and the time as they’re quick to configure. If needs be, an attribute value can act as a proxy link if it stores the (unique) title(s) o notes, i.e $Name.

Hi Damien,

It’s hard to say exactly what might help you as I’m not entirely sure everything you want to track, but it seems like you could get by with just a few $KeyAttributes. Every “piece of information” that comes in could be tracked like so:

$Name: Specifications for brand x website
$Client: Joe Blow
$Project: Brand x website
$DueDate: 4/1/17

$Name: draft copy for press release
$Client: Jane Smith
$Project: Secret project
$DueDate: 6/1/17

(in the above examples, you need to create the attributes $Client and $Project)

Then, you could create Agents that represent each Project or Client, with the following queries:

$Client==“Jane Smith”


$Project==“Secret Project”


you could combine them:

$Client==“Jane Smith” & $Project==“Secret Project”

Or, as others have suggested, you could use the attribute browser, with $Client or $Project selected. This would then give you a list of all notes grouped into either Client or Project categories (and you could then further sort by additional columns. So you could group by Project, then sort by Client, or vice versa.

The way I see this, there isn’t any “hierarchy” being imposed, nor is there a bunch of different prototypes to deal with.

1 Like

Building on this, what if you’ve now got lots of clients and projects and don’t want to have to set up a permanent agent for each client/project combo? There is a designator that can help - ‘agent’. This can be used in an agents query and action to refer to the agent’s value for an attribute. Thus the above query could become:

$Client==$Client(agent) & $Project==$Project(agent)

Make $Client and $Project key attributes in the agent. Then it’s easy to swap “Jane Smith” for “Louise Brown” in the query by editing the $Client item in the agent’s key attribute table. The next time the agent evaluates, the new value is used. You could also make the agent’s display expression report the current client and project values to remind you what the agent’s currently querying without having to look at the agent’s text pane.


@derekvan and @mwra thank you for the thoughtful suggestions. Mark, I especially like your suggestion about the agent designator, that looks like it would be very helpful.

Derek, what you suggest makes sense, but I am still at a bit of a loss as to the best way to handle inter-note relationships. Lets say I have a note with $Client and $Project attributes, and that note describes a phone conversation with that client about that project. As a result of that conversation, I generate several $Prototype=“Task” notes. I now want those task notes to refer back to the original conversation note for reference. Doesn’t that seem like the right use for links?