Tinderbox Forum

A cordial community

I’m curious whether you mean to suggest a lack of coherent documentation. There’s tons of that, far more than I am able to process.

Tutorials are different. They’re scattered around in various places. But if you ask questions this whole forum becomes one big customized (and resource efficient) tutorial.

1 Like

Sumner, I think I understand what you’re saying but I’m not entirely sure.

In one sense the forum might be viewed as a living tutorial. The act of posting and reading responses might be considered to be the tutorial in action. It’s a very resource efficient tutorial since a poster’s exact challenge is being addressed. Bravo to the community for that. But that’s not really a tutorial. A tutorial should guide the user. It shouldn’t have to be poked and prodded with questions to guide the presentation.

In an another sense the forum is an abysmal tutorial. If you choose not to ask a new question, but rather work through the existing forum posts to learn things, it would be easy to get lost. I don’t think you mean to suggest it is a resource efficient tutorial in this regard.

The forum is great but no substitute for documentation or tutorial.

Tutorials work best if the app (or its users) are trying to do one, or a small number of things. That describes neither tinderbox nor its users who vary widely in familiarity with tech(nical abstraction) or in their desired task. Based on experience, users are more outraged by tutorials covering someone else’s task but not their own than they by no tutorial. some here have the scars to prove that. Counter-intuitively perhaps, a lively and helpful forum is actually a pretty good solution.

The issue is partly that there are a lot of smart people here who are quite used quickly acquiring understanding of new things. Faced by something not so quick to understand it rapidly becomes a zero-sum game of who (i.e. someone else/thing) is to blame for this apparent failure. But, no foul; it’s a very human reaction. As @eastgate pointed out tonight (I forget in which thread) difficult tasks may seem simple—in the mind’s eye of their eventual outcome—but are still not simple to do at first attempt; some learning is required. I say acknowledging my own transition along that path from my initial use of the app to more considered use now.

1 Like

I’ve seen very successful tutorials on products that are orders of magnitude more sophisticated than Tinderbox. The difference is that the companies and communities behind those products and tools are much larger - and they have the resources and will to actively engage newcomers and draw them in.

I find Tinderbox kind of easy. My background makes it so. Tinderbox is a brilliant piece of work. It’s inspired. That’s good enough for me as a user. But it doesn’t justify all of the challenges.

What is the correct venue to hammer out some ideas? This is a very strange forum. Sometimes it’s strongly asserted to be just a user-to-user forum. Sometimes the company (@eastgate - not sure if that’s one person or more) jumps in. How would you even approach collecting user ideas for improvements?

So, it’s a cordial community. Where can we go to be nasty? Where can we go to openly discuss areas for improvement without hurting feelings? Where can we go to discuss things which are not actionable - till they are?

Hi Barry,

Perhaps it would help if you could give specifics on the products “that are orders of magnitude more sophisticated than Tinderbox” that have “very successful tutorials.” That way we can all get a feel for how comparable they are to an open-ended tool like Tinderbox.

Tinderbox has some similarities to spreadsheet apps. They can easily do simple things, as can Tinderbox, but they can do a broad array of sophisticated things too. They often have no one “correct” way of doing something. I’ve never seen a truly satisfying tutorial where one can learn “everything one needs to know” about Excel, or Numbers. The really valuable, practical sources tend to be forums.

What I meant by this forum being “resource efficient” is that it doesn’t place undue demands on a particular tutor (though Mark A may disagree!:grinning:) to keep every single passage tidy and up-to-date. Yet highly tailored, up-to-date answers are quickly available.

To me the facts do not support your suggestion that Tinderbox does not have extensive, coherent documentation. It does. The case is stronger for saying there are too few tutorials. But it might be a good idea to go back through the items in the Help menu and the various other tutorials at the other end of links from this forum before pounding too hard on that assertion too.

1 Like

Hello All

I’ve been following this and the related discussions on the forum. In fact, I’ve been following the forum for several weeks now, more or less reading every thread. I’m new to Tinderbox, so I thought my view might be relevant.

I should say that I do not find Tinderbox hard to understand, but I have a programming background and I’ve used a lot of software. Tinderbox most reminds me of HyperCard and I think that is one reason I find it straightforward to grasp.

I agree with those who think there is no proper documentation. If I compare the documentation that existed for HyperCard, particularly of the HyperTalk scripting language, there does not seem to be anything comparable besides atbRef. The fact that the company does not provide that reference seems to me odd. The built-in help seems to me superficial and certainly would not suffice to learn Tinderbox 7–the version with which I started. I have not read the Tinderbox Way, because (a) I’d rather buy the new edition; (b) I’m troubled by the thought that some essential documentation must be purchased. I doubt that it is essential.

Now, that being said, I used (i.e. did all the steps) the built-in Getting Started with Tinderbox tutorial and that was very good. I felt that I had learned all the basics having done that. I also read the tutorial on Actions and Dashboards, which I found helpful too. (I couldn’t bring myself actually to do it, because I have filed too many expense claims in my life already!) Having done those diligently, I felt able to proceed.

In my experience–and this counts against many tutorials–one needs a “real” project to work on to learn some software. Only when you’re trying to solve your own problems, do you have the motivation that produces learning that sticks. So I would agree with those who are reluctant to make the considerable investment required for more tutorials. In my case, I used a limited dataset, and a limited scope project, and worked through it. I did not go for my big project, i.e. the reason I invested in Tinderbox, yet. I am working on two more intermediate projects before I attempt what I think will be a multi-year project.

In doing my first project, I ran into difficulties straightaway, even after consulting atbRef. Here the community on this forum was great, with quick, detailed answers. I would have been reluctant to send my questions to a support team at the company–I guess because they didn’t seem like bugs, but more “how do you do x”–but knowing this community is here is invaluable for Tinderbox.

A few months in, I am now a convert to Tinderbox. It really is a remarkable piece of software, quite unlike anything else of which I’m aware. It is clearly very flexible and powerful. My sense is that the learning curve is steep, then shallow, then steep again. You need to do quite a bit up front to get what Tinderbox is and what the basic constituents of a document are; then you can do quite a bit without significant knowledge of the scripting language; then you’ve really got to get your arms around the (somewhat unusual) scripting language.

As an aside, I have wondered about using Tinderbox for years. Two things put me off. First, for a long time the user interface seemed to me very ugly as if it were port of a Mac System 7 application to OS X. Second, despite scouring the Eastgate website, I really could not divine what it did. The UI is quite a bit better now and I stalled on a big project and decided to take a leap of faith with Tinderbox as the solution.

For Eastgate:

  1. I think reference documentation (esp. on scripting) should be provided by you; or perhaps assured by you through atbRef or a successor.
  2. I think your two built-in examples are good and sufficient for everything bar export (though the expenses topic of the second is somewhat depressing and unrealistic since expenses inevitably go through a Finance-mandated submission process).
  3. I think your built-in help on export is inadequate. I think you need a built-in example, comparable in detail and scope to the other two (in #2). The closest thing I’ve seen is Brian Crane’s (?) examples on his website. Apart from frustration, this is evidently a great strength of Tinderbox that is hard to understand or harness at present.

For the community:
I have got much from the ambient absorption of information by following threads and the direct help rendered by those who swiftly answer with excellent solutions. Thank you. The two areas where I hope for more are examples of how people use Tinderbox to complete activities; and inter-application workflows to/from Tinderbox especially with mobile devices. Examples of the first are answers to the recent threads “Where do you put your x notes?” and examples of the second are answers like “I use DevonThink To Go synchronised and exported to Tinderbox.”

Thanks again to the community and its recurrent contributors. Without doubt, you made and are making Tinderbox work for me.

David.

7 Likes

Hi Sumner,

I agree that the forums are resource efficient with respect to sharing the load. I had thought you meant resource efficient as a tutorial. That is, the person trying to learn would find it an efficient resource. So, there’s no disagreement there, just my understanding of your point was off.

As an example of a sophisticated, open-ended tool, take a look at https://www.jetbrains.com/idea/documentation/. I’m not going to speak for Eastgate; I’ve been chided before. But, I can say that if Eastgate is a small company there wouldn’t be the resources to follow through with this kind of offering. To make any headway there would probably need to be a person whose job it was to handle user education.

Excel is a very sophisticated tool. The Microsoft provides some help at https://support.office.com/en-us. Also, the user community is vast. Tutorials and many topics are very easy to find. I did look around the web for Tinderbox references. I’m not going to speak for Eastgate, but it appears that the community is very, very small and has very little web presence.

There’s no blame from me leveled at Eastgate for not providing this amount of help.

FWIW, Eastgate is a small company.

I am this forum’s mod/admin am not formally associated wirth the company. I am the (sole) author of aTbRef (of all 6* editions online). With the agreement of Eastgate, aTbRef is published under a v4 Creative Commons licence (by-nc-sa); see here for waivers, more info, etc. I also contribute to the Tinderbox Cookbook and assist with some aspects of the app’s manual (e.g. TBX export templates for use in making the PDF version). All these activities are my own volunteer effort, in part precisely because Eastgate is a small company and thus has limited capacity for making extensive support materials.

*Baselines at v2.3.4, v4.5.0, v4.6.0, v5.0.0, v6.2.0, v7.1.0.

Not quite. Tinderbox was first published c.2001 which would put it on System 9. The codebase was ported from Metrowerks (i.e. pre-OS X) to XCode as from v6.0. Previous releases can be seen here.

Thank you for your post David. I enjoyed it quite a bit.

Aha, that explains a lot. I remember Metrowerks from a very long time ago.

Is there a version of the Cookbook newer than 2.0, which appears to target Tinderbox 5.11.2? That apparent fact made me chary of using the “recipes” there.

David.

The last update I made was at Tinderbox v7.0.1. It looks as though that’s not yet made it’s way to the public webpage (here) which is an old version as you report.

I’m sure that can be updated.

Indeed, this is a particular shame given that exporting to other (text-based) formats is one of Tinderbox’s unparalleled features. I’m not aware of any other program that provides the ease and flexibility that Tinderbox does in this area (once its features are understood). It would be valuable here for the documentation to emphasize the fact that Tinderbox’s HTML export facilities are really arbitrary-plain-text-format export facilities, and work just as well for LaTeX, Org Mode, and Markdown as they do for HTML. In addition to being useful for newcomers, this would also allay the fears of more technically minded potential buyers who are nervous about their data being locked into a strange format.

I’ve branched some discussion of this to a new thread focused on formatted, i.e. ‘HTML’, export. I’m trying to figure the key missing aspects of existing materials other than the catch-all of being ‘better’. Practical input welcome over at the other thread.

Paul, I think the data is effectively locked in if the export functionality is not used.

I’ve worked with the xml data programmatically. While the note data is readable, it is impossible to get a sense of the relationships and how the diagrams would look. If you wanted to recapture the information in the XML document you would have some development work ahead of you. You’d want it presented in a way that can serve you for quite a while. That development might be impossible or very hard for a technical person. In any case, there would be a large time commitment that a user might not be able to make. As long as a vendor publishes the schema of their SQLite database, XML format has the same challenges as SQL format.

Tinderbox has done the heavy lifting of getting the data out of the program. In my mind, that’s what avoids the lock in.

2 Likes

I was typing up a response but @burnwa spoke my mind.

I think we’re getting into some unfruitful angels-and-pinheads debate here. Unless you have an app like Tinderbox - or write - you’re not going to re-create all the data you can access in the file. Although the rich text is in RTFD encoding, the plain test of each note is retained as such. XML might be painful to read to someone unused to it, but you can put it in a text editor and see readable text.

The comparison being made to SQLite is moot for a non-technical person, i.e. those at most risk from lock-in. I don’t think you can easily look at SQLite data as easily in a text editor as you can XML.

The more useful distinction is that TBX data is not in (undocumented) binary format; that would be lock-in. This distinction was more pertinent going back a few years where more apps did use binary-encoded stored data. It is the case that a lot more apps now used XML (or similar) formats to store app data. That’s a good thing.

Please don’t anyone rad this post as censure. However, I think it important to make these distinctions as whilst tech hair-splitting is idle distraction for tech folk it’s confusing for those who aren’t and that includes many of Tinderbox’s users.

My main purpose was to extol the virtues of the Tinderbox export features (and, I suppose, to bemoan their lack of proper exposition in the shipped TBX documentation), which make it a cinch to get your data out of Tinderbox, in whatever format you please, whether to publish on a web site or export to another application. This makes the underlying data-storage format relatively unimportant. This is not hair splitting. The fact is that in the absence of such functionality, “exporting” would amount to copying and pasting the data out of the application for many users — something which can be done from any text-based app, regardless of how its data is stored at the file level.

.docx files are XML as well, but that doesn’t mean that data is easy to extract from them in any meaningful sense. Similarly, just because the text of a note is easy to find doesn’t mean that the view you have created on the data within your TBX document is easy to extract from the XML file. That’s where Tinderbox’s export features make all the difference, especially (now that I think of it) for people who are of a less technical bent.

1 Like

I can see that focusing on document structure might confuse some people. It’s easy to wander off on topics some people (me!) enjoy.

I think technical and non-technical users should take comfort in the export feature, not any particular file structure. Given the breadth of information and understanding in a Tinderbox file, no direct review of the underlying structure will be helpful. Mark, your efforts to help document the export are very much appreciated. I look forward to learning a lot from the discussion. I probably won’t participate since I don’t know anything about export.

Thanks @galen and @burnwa, all understood. I’ve already started threads in the Tutorials sub-forum re ideas for better explanation of the process for those who’d like to offer suggestions. I agree it’s chick-and-egg with (HTML) export. Tinderbox’s export is very powerful, though takes a while to master as ideally you need to have some sense of quite a lot of Tinderbox concepts: action code, export code, outline order, prototypes, etc. Not all things you know on day one. the Text export is simpler and does ‘just’ export text pretty easily which should be good for the least tech users who likely only use $Text rather than a lot of action code.

1 Like