Teaching Tinderbox

Q & A - getting started with Tinderbox
31

This is, ironically, a good example of the problem. What “text” is being proposed? The question isn’'t flippant.

That said, were it the textual part of the note (the bottom section of the text pane holding the $Text) the controls are all on on the Format menu’s sub-menus - which are easing found by typing ‘text’ in the search box at top of that app Help menu (as holds for any macOS app with a Help menu).

I was surprised that of the 3 resources on the Help menu (app Help, and the 2 PDFs), none explicitly talks about styling the contents of the $Text area. Now discovered I’d suggest that is an oversight worth reconciling.

By comparison, the Help and PDFs do talk about how to make notes bigger change color. But if people won’t head the Help resource(s) where is it proposed such information be stored?

It would actually be useful is people actually followed through on complaints of not finding explanations by explaining what that were looking for, or the terminology used. I often make that request here, but I don’t recall anyone ever making a serious answer (i.e. a list, not just one suggestion). That’s a general observation and not aimed at @MartinBoycott-Brown. But, seriously, it would help to get a better handle on how people expected to locate information. The fact that there are gaps would suggest it is harder for the documentation writer to guess than the user might like to imagine.

32

At the risk of dating myself, the approach I took to learning Tinderbox (after a decade or so I am still learning) was to view Tinderbox as the “erector set” of note taking. Knowing that there was always a shining object in the box within reach served as a source of mystery and comfort. And again, if I decided not to use the shinning object in the box that was OK too. I could still build a note taking widget of my own making.

1280px-Erector_Set
1280px-Erector_Set1280×960 303 KB

Image of a modern day Erector Set.

1 Like
33

It was late at night when I wrote and I should have reflected a bit longer, as I have missed out some things that would (I hope) have made my thinking clearer. I will try to clarify.

The title of the thread is Teaching Tinderbox. To my mind, teaching is different from documenting. If I can go back to (human) language again, The Oxford English Dictionary is a wonderful repository of information on the English language, but I would not want to use it as my main tool for teaching the language. Nor would I (normally) want to teach someone English by first teaching them the conjugation of the verb “to be”, etc. Some people would thrive on the grammar-based approach, but I suspect they would be people who already speak a second language. In most cases I would prefer to use a book that presents little scenarios, like ordering food and drink in a cafe, asking a person for directions, checking in luggage at the airport, and so forth. This seems to be a fairly standard way of teaching/learning languages nowadays.

All sorts of people successfully learn foreign languages using this approach. And languages are far more open-ended and complex than Tinderbox. There was a joke about a person who always ordered steak and kidney pie in a cafe because that was the only thing he had learned to order, but in reality most people are able to use the scenarios in their text books as a basis for building other interactions. I think a number of short tutorial videos in a similar vein (five minutes or so) would help to ease the beginner into using Tinderbox, and maybe help the intermediate user to progress. I have just started using some screen capture software, which is simplicity itself compared with Tinderbox, and the tutorial videos have been a godsend.

In short, I feel that teaching/learning material and documentation/reference material are (or perhaps should be) different things, though obviously linked, in that reference material is sometimes needed for learning.

When it comes to the documentation, I hesitate to step into that minefield. If I had any spare time (which I have not, at the moment) I think I would start a Tinderbox document in which I did a sort of “thematic analysis” of the program with starting points like “Appearance”, “Searching”, “Organising”, etc. and construct trees leading from the general to the particular. There would no doubt be links crossing between the trees. Tinderbox would seem to be a natural tool for conducting this sort of analysis or “re-picturing” of its own functions and capabilities, so I’m a bit surprised that such a document doesn’t seem to exist – but I realise that people have other things taking up their time. I think it would be a bit easier for an inexperienced user to follow a “tree” of this kind than it is to navigate more conventional documentation. And just to be clear, I am not criticising conventional documentation. It has perfectly good reasons for being structured in a particular way. But it would be interesting to consider whether other structures are possible or useful. And they might not be – though I guess one sort of structure would not necessarily preclude the existence of another. All the academic books I have are divided into sections and chapters, but also have indexes at the back, sometimes more than one. But I’m thinking out loud, and maybe not all that deeply!

I shall stop before I completely disappear in the quicksand!

Best wishes to all,
Martin.

1 Like
34

Indeed. The fact that other structures aren’t being used is perhaps those who know of them are for some reason reluctant to explain them to those who might use them. I don’t think it’s a case of authors deliberately choosing not to use those structures. Suggest away!

Absolutely, and now Erector™ is owned by Meccano™, I like to think of Tinderbox as “Meccano for the Mind”. Build it, and the insights will come: filling in someone else’s design, not so much.

35

Filling a gap discovered above, I’ve just expanded my aTbRef note on the ‘Text area’ (i.e. where $Text is displayed) to give better description of the controls for altering text: see here. I’m not suggesting it is the ideal answer for the learner but I hope it is a stopgap until formal documentation is updated.

36

Here here! Thank you Mark. I find Tinderbox is at the intersection of art and science. :slight_smile: Perhaps the framework below could help for some that are trying to approach the Tinderbox forum with a question:

My goal, e.g. I’m trying to achieve x, y, or z (the goal can span the gamut…“how do I add a note” to complex query strings, export formats, and query strings).
What I’ve tried, an explanation of what you’ve tried to do, you can include pictures and sample notes/queries/expressions, etc., upload a demo TBX file to illustrate your efforts. Also, can list: My Expected results are and what I ended up with. For example, “I opened up a new file, added a note, and now don’t know what to do,” to “I wrote this export code and it is not working as expected.”
A plea for help, “Can someone help me? I really stuck and don’t know how to move forward.”

There will then be a back and forth…

My personal experience is that the community rises to the occasion and I end with 1) my immediate question/issue addressed, 2) one or methods on how to address my issue, 3) greater clarity and reduced ignorance of myself an the tool (Tinderbox has driven a massive internal discovery and revolution for me), 4) more confidence in using Tinderbox and in tools that work with it to accomplish my goals, 5) gratitude and a new set of tools and experiences I can then use to achieve my current and future goals and to give back to the community, 6) new friends and exposure to ideas, thinking, and concepts not traditionally in my wheelhouse.

I’d like to reference our recent exchange as a good example of this framework in use: Conditional Export for Due Date - #21 by mwra

1 Like
37

Totally agree. I think there is a continuum of tasks:

1. Primary use case, .e.g. write articles, analyze an industry, write a book, manage a survey, manage a sales pipleline, write my dissertation…(I’d love to get a top-level list of people primary use cases )
2. Approaches, list of specific approaches to achieving the primary use case
3. Moves, specific moves people can take, like changing a color.

Maybe it is because I just watched the Queens Gambit, but seems like Tinderbox is a lot like Chess and more, more because it is not bound by the 64 square limit of a chess board, but actually has infinite options.

Just like chess, I think there are opening moves, and strategies that can be documented, but ultimate the paths to “winning” grow exponentially as you dig in. In the end, once you lean how to move the pieces and and understand the most common moves and strategies (the science) Tinderbox opens you up to a way of thinking – collect, connection, curate-- and contribution (the art).

1 Like
38

Lots of people start their Lego and Erector explorations by building other people’s designs. Then they tweak existing designs. Then they design more and more ambitious projects of their own.

2 Likes
39

Except actually they don’t. At least not for human players. Human experts spend a lot more mental effort on pattern recognition and general principles than they do on tactical calculation. There are an enormous number of possible paths, but only a very small number of them are worth evaluating, and only a few of those will lead to a win. A major goal of chess instruction is to equip – usually through analysis of critical positions – the student with the intuition to prune their mental variation tree.

Similarly, Tinderbox may offer an enormous number of possible paths, but users don’t necessarily need (or want!) to explore all of them. The goal is not to become a “Tinderbox expert” but to accomplish whatever their primary use case is.

2 Likes
40

I envied the kids who could just buy the answer and play with it, I was never lucky enough to have all the parts, but I did learn from those who explained how I might use the parts I did have to make cool things.

TL;DR. Let’s try and be a bit more inclusive. We all start from different places.

41

i disagree with your notion. No one has to be an ‘expert’. But we should never be too proud to learn or ask from help from others with a tool which is about learing and analysis and not finding/buying (qv your last post) the way to the answer . Anyone can throw stones.

42

I’m not sure how suggesting more tutorial examples is a less inclusive position.

43

I was commenting on the quoted text. I’m unclear how that reflects on the number of tutorial examples.

The majority of ‘examples’ available represent efforts made for free by you fellow users. If you explain your need clearly, I’m sure people will ttry and help.

As I’ve said, anyone can throw stones. Pewrhasp, instead of being so negative, if you asked for help—it’s not demeaning—your fellow users might help. This is one of the most helpful forums I’ve used, in 30= years of such activity. I’m truly saddened that you find only things to complain about. That said, like others here, if you have something we—as users—can help with, I’m sure myself or others may have a solution.

Meanwhile, I’d encourage later reader to review the fisrst post in the thread. @eastgate asks some entirely pertinent questions. In answering we can chose to be part of the solution … or simply throw stones. I’d hope users would cleave to the former.

Let’s try and help one another. Knowledge work is hard without unnecessary strife. Entitlement, even if unintentionally acquired—we are all prone to it—is a scourge of collaborative work.

44

I agree with you, and it looks like I may not have been clear. That is what I meant with " I think there are opening moves, and strategies that can be documented." We don’t need to show everyone everything, we just to to help them understand how the pieces work and lay out some basic opening strategies so that they can have fun playing the game, using Tinderbox, getting done what they want to get done. We’ll get there. :slight_smile:

1 Like
45

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.

46

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
47

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.

48

@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

49

That makes me feel both better and worse.

50

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