The problem is that a not-uncommon attitude around the forums seems to be that people who struggle with Tinderbox are unreachable because they are in some way lacking in some of the non-technical skills you list.
Which, since these people are sufficiently functional in their daily lives to have complex jobs that might benefit from Tinderbox, is insulting, wrong, and a convenient deflection from the very real limitations of Tinderbox’s tutorial materials.
One reason that I so often ask for context is precisely this: knowing the big picture, real task that underlies a problem often helps identify opportunities.
Late to this discussion, but one thing Mark brings up in his original post is something I have noticed for a long time. I’ve used Tinderbox since version 1, so should have a decent rule-of-thumb knowledge. But because I have no computer programming skills whatsoever, I always have to remind myself “What is the expression for this” function I want to perform, look it up, etc. It’s a bit like reading a foreign language you don’t speak. You might be able to decode a familiar word or expression and even use it, but if you don’t know the alphabet, grammar, etc. you almost certainly can’t remember it over time.
So, is it Tinderbox’s responsibility to teach me programming? Absolutely not. But having been in many of these discussions, I suspect there are a lot of people like me, nearly ignorant of any programming. We might benefit from some suggestions about how to acquire these basic skills, sites on the web, books, etc. I recognize that most folks are so far beyond this it’s hard to imagine, but some users must either be teachers of code or remember some more simple place to start and acquire these basic skills. And I do know there are hundreds of sites on the web to do this. Just suggesting that a more structured “if you want to know these basic functions, learn X skill set and here’s where to do it” would be helpful from the community.
I’ve noticed. Knowing the context can also help reframe the problem in a more Tinderbox-friendly way, as opposed to trying to re-implement an existing solution in Tinderbox.
And also being upfront about “Yes, this is a programming task, and your life will be easier if you recognize it as such.”
Honestly, I think that is a source of a lot of newbie confusion (including my own continuing ;). There are lots of little programming tasks built into Tinderbox that are so basic that anyone who has done any coding at all regards them as trivial. But for many new users not only are they not trivial, but (and I realize this may be hard to believe) they aren’t immediately recognizable as programming tasks. Again, no one’s fault, least of all Mark’s. Just a more general awareness that programming is involved and there is a basic skill set you need to be at all fluent.
@kderbyshire Going back to a few of your comments, BTW. Please note, all of my comments are rooted in my attempt to be better. For example, do I know how to write? Sure I can, but can I be better at it? Absolutely. Do I know how to think? Sure, but could the results of my effort be improved, changed, or modified for the better by learning how to think or view problems differently? The answer for me, at least, is without a doubt is yes. Also, to your other example, some people know how to “caramelized onions” (I actually don’t) while other may need the basic steps on how to sharpen a know and cut the onions. I don’t’ think it is patronizing to lay out all the steps needed. It is not a judgment on anyone, it is simply laying out the steps. Maybe I’m wrong, but I’m simply looking for completeness, to which Tinderbox is just a part.
One significant constraint that may not be evident to everyone: Tinderbox cannot say that it requires programming. Unfortunately, a large portion of people who could benefit from Tinderbox believe that they are “not programmers” and will abandon anything that expects or requires “programming.”
This is unfortunate, but it’s true. The pool of self-identified “programmers” is not sufficient to support Tinderbox, and so it is simply necessary that we work around this constraint.
The ‘two tribes’ raise their ugly head again. I’m not a programmer—and lack the aptitude. I don’t buy the “oh it’s technical, I _can’t understand” mantra I’ve detected above. Othering that thing—or those people—who have different skills is not helpful.
I came to understand Tinderbox not because I cleave to the Arts or the Sciences (as if these are innate binary human conditions), but because I wanted to solve a problem where other tools had failed me. If you are from an arts background and learn how to write an action, you are not diminished as a human.
I also don’t buy the self-regarding “I’m smart so if i can’t understand the app it must be dumb and badly made”. That’s just an unwillingness to accept we find some things hard, or unfathomable. My experience, when struggling is to ask for help and try and explain how and where I’m lost. Just abusing those who would help because they don’t intuit my special needs seems self-serving.
Learning the deeper parts of Tinderbox isn’t some performative competition. Even if none of it makes sense, you can always ask for help—but do remember not to sneer at people who understand something you cant’t or worn’t understand. Not least they give their time and effort, for free to help problems that only you may have. Does such assistance deserve sneers about ‘technical’ expertise.
It’s hard to help people who forgotten how to treat others as fellow humans and just demand and give nothing in return.
The Tinderbox community is a broad church. We have lots of people from all sorts of walks of life, be they ‘technical’ or not. So, as your forum moderator, can I ask us all (so as to single out no one person) to be a bit kinder and more generous.
Over the 16 years I’ve assisted this community, the most compelling stories are those who fought through their prejudices and false assumptions about how things must be (be they ‘technical’ or ‘non-technical’, whatever that means) and asked for help and acted on it.
There are improvements that can be made to the range and type of learning material available, but a lot of what I see are pre-emptive barriers: "I won’t use assistance unless it meets my following conditions (which invariably then aren’t explained). I both write and use documentation, the best interactions are people who don’t just say “it’s all rubbish” sort “it’s not written for me” and flounce off. Better are those who say where they get stuck and what concepts are blank to them. Tellingly, the’ve made an attempt to understand, and their comments yield real insights which I certainly put to use in what I write and make.
So, instead of asking for “easy” or useful" or “pertinent” which are all subjective, please surface where you get stuck. If you’re not sure why, explain what you imagine (intuit) will happen, and be open enough to understand so thinks may work in ways you personally don’t understand.
I’ve accepted that I’ll never be a programmer. As non-programmers, Tinderbox’s internal scripting may seem like ‘coding’, but that’s unfair programmers; the latter is more complex and nuanced. If we set aside our pre-emptive rejection of what we disparage as ‘code’ it leaves us more open to leaning. If I can learn it, I’m unconvinced others can’t if they would only stop convincing themselves they can’t.
TD;DR You can if you try, and are not embarrassed to ask for help.
Aspects of my background that are relevant to teaching things:
My thoughts:
“I’d like to distinguish three kinds of difficulty”
I find myself wondering why. I actually don’t think that is all that useful in this context. I think it would be more useful to identify different kinds of user. Effectively, the kind of difficulty depends on the kind of user, rather than being an independent objective quantity.
Computer program documentation sometimes seems to come from the “wrong end” – it comes from the programmer’s point of view, not the user’s.
Users are likely to be “task orientated” – they want to do something.
I have found it very difficult at times to find out how to do things in Tinderbox because of the way the information is structured. I have sometimes wandered around the documentation for an hour, thinking to myself “but I only want to [insert simple operation]”, forlornly trying different possibilities, before giving up and asking someone. The documentation is marvellous if you already know what you are looking for. At other times the categories/nomenclature are a hindrance rather than a help.
I suspect that newer users would benefit from information structured in terms of tasks they might want to perform (e.g. how to make a note bigger/change the colour/find something/change the appearance of a lot of notes/you get the idea). This would be easier to unpick than categories like “Action Code”, “User Attributes”, etc. How would I know which category to search through if my task is framed in terms of “I want to make the text bigger”?
I do volunteer work counselling, and about the most important thing of all is being able to see things from the client’s point of view. If you can’t see with their eyes, it is not going to work.
And at the risk of being self-indulgent, I seem to recall that von Humboldt said that you cannot teach languages, you can only create the conditions under which they can be learnt. I believe it applies to a lot of things, not just languages.
Cheers,
Martin.
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.
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.
Image of a modern day Erector Set.
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.
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.
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.
Here here! Thank you Mark. I find Tinderbox is at the intersection of art and science. 
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
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).
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.
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.
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.
