How to find the right operators to complete a task?

Agents, Actions and Automation
1

@brookter (here) noted the difficulty of discoverability of Tinderbox functions, the issue here is how to map outcome-based logic (“I want achieve outcome X”) to a functional descriptions (“This operator does thing Y”).

As a resource, aTbRef is already large and I think adding a section with such mappings might bloat things even more, though I’m open to suggestions. However, I do make an effort to keep aTbRef URLs stable, and elsewhere possible even stable across different baselines (v6, v7, etc.) and keep the old baselines online. So, perhaps, the answer is to start a new resource—perhaps made from a TBX—and cross link those pages to things like the aTbref operator pages. I’d be very happy to host such pages and ‘own’ (for the community) the TBX & output pages, etc.

If the latter idea makes sense, what is needed is a bit of community discussion about how best to frame this mapping. Questions too closely linked to the (imagined) result are not good as a base as generally they are based in a task others may not do.

Perhaps we need a two-level sort. IOW, we have pages telling you things you can do with strings vs. lists linking through to the detail in aTbRef. Then the “I just need to…” type outcome-based descriptions can be pointed to that layer. As I write this, it seems like extra work, but I think it might be worth doing. It will essentially be taking task-based descriptions and abstracting the necessary step(s), even if this abstraction is hidden from some using such a resource and whom can still get to an answer.

In short, I’m trying to think how to help people to bootstrap themselves to an answer from the available resources (and learn in the process) rather than have to ask an another person as the available resources are not clear enough for them.

2

TBF, my problem was initially from not finding the .words operator that I felt ought to be there, but which I couldn’t find. I looked in the right place (the site map), but just didn’t see it.

The real issue was trying to recreate it and I got a bit lost with the syntax and application of .each(). I found the function easily enough, but got a little lost in applying the examples to what I wanted to achieve. (Possibly because the examples start with a relatively complicated task of exporting to html and uses other dot operators such as .format. Now I’ve had more time to look at, I’m more confident I understand it.)

Would having an index with “How to do loops” have helped? I’m not sure, because I got to page with no difficulty. I’m comfortable with atbref though, so am not the right person to ask, probably.

None of this is criticism of atbref, BTW: it’s excellent and I use it a lot. Thanks!

3

I think over the years this community has had numerous resources, community-sponsored or Eastgate-provided, that started enthusiastically and petered out. Not from bad intent, but because volunteer documentation is hard to sustain. @mwra’s ongoing sponsorship of aTbRef is rare and extraordinary for a software product.

That said, “how-to” help is notoriously difficult to produce and will always fail to anticipate common use cases. (Not an off-the-cuff opinion – I write from experience of decades of involvement with well-funded IT solution implementations.) When a similar question came up in the Tinderbox Backstage forum, my opinion was not that the documentation we have is faulty – thanks to @mwra it is stellar. But --I think this forum is the best way for users to find the answers to how-to questions:

  1. Primarily, because there is rarely one method to provide “how-to” help for any given use case. The forum is an excellent platform for providing readers with multiple takes from different voices on solving a given case.
  2. The forum we have here (based on Discourse software) already has features to help with discovery of how-to answers: (a) tagging, (b) we can flag answers as “solved” (that feature is not yet activated in this forum, but could be); (c) “wiki” posts (also supported by Discourse but not yet implemented here) can be used to link together threads on the same or similar how-to questions, and (d) we can all learn to be clearer in giving titles to post that some things are [Questions] or [Answers] or whatever other “flagging” in titles grows up here organically to help other readers.

So, let’s as a user community, use what we already have. @mwra’s volunteered solution in the original post is, as usual, extraordinarily generous, but I think we as a community have no basis ask any more from Mark than he already does – and the community should use the community resource to help others in the community increase their Tinderbox skills and familiarity.

@mwra highlighted a problem – I think it is up to all of us to pitch in and solve it. The forum is a pretty big tent (800+ registered users) - let’s continue to use it for the benefit of readers from all points in the spectrum, from superusers to newcomers to Tinderbox.

2 Likes
4

I can only give the last one ‘like’ but it deserves several for the range of issues it summarises well. Thanks, @PaulWalters.

1 Like
5

I think @PaulWalters makes some valid points. But speaking as someone who is rather outside the group of committed Tinderbox users (someone who is more a “dabbler”) and someone who has struggled with the program, I would offer a few observations.

In order to make use of a resource you have to know, or intuit, that it is there. And you have to know, or intuit, what it might offer.

I don’t know what might be done to aid discovery, I leave that to others to ponder. But I would suggest that the Tinderbox forum is a bit unusual in that people here are more helpful than they often are on “the internet”. You never know what to expect when you venture out into the wild. Anything from RTFM – sometimes in plain rather than abbreviation – to a lot of help. My point is that until you have dipped your toe into this forum you don’t really know what to expect. And past experience might dissuade a lot of people. On this forum I have been astonished by how often people have asked for help and how someone has constructed an example Tbx for them, complete with agents, queries and prototypes. Perhaps showing a few of these as examples of the willingness of others might help. Call it “priming” or “seeding” if you like.

It might be worth considering if the way this forum is set up (the way it is structured) is helpful to new users seeking information. To be confronted with sections entitled “Tinderbox Tasks; Q&A - getting started with Tinderbox; Tutorials and Examples” might well be confusing. Even the sub-text for “Q&A - getting started” is muddied. Is it for new users? Or experienced ones who have forgotten something? Why isn’t there a section that boldy calls itself “New Users”? Or something similar.

We all know that search boxes are great for finding words and not so good for finding concepts. How that conundrum might be solved, I don’t know, but more tagging might help, as Paul suggests. Though how tags might be used to identify processes is more difficult, I suspect. And there are lots of processes in using tools like Tinderbox. Another one to ponder.

I could go on, but I think the most basic help that could be given to anyone starting is to make it clearer where to go, and encourage them not to be timid about seeking help. Who knows how many users never see these pages? And who knows how many found the pages themselves too confusing? I certainly didn’t know what had hit me the first time I arrived all those years ago.

As an aside, I suspect that most people who use Tinderbox are relatively computer literate, or they would never have tried it, but you never know what you might encounter. I have a friend who is a senior academic, and I was once helping him sort out some stuff on his computer. I double-clicked on a file to open it and he looked rather started and said “I didn’t know you could do that”. He had been laboriously selecting something, then using the enter key. Help sometimes needs to start at a lower level than we might think.

1 Like
6

The TL;DR here, is we’ve tried most of these things and they just don’t work. I have the scars on my back to prove it. Meanwhile, I’m always happy help people who politely ask for help. Part of the issue with a toolbox like this is people think they are using a utility and the task they are doing is the main purpose of the app and therefore the answer should be simple (‘intuitive’) because there should be few choices (as in a utility). If Tinderbox were a one-task utility this would be true, but it isn’t.

Demos are massively consuming of time; I done enough to know. Making the file is the small part. Setting up the test data, including edge cases, etc., and documenting the process for anyone who might later read the file takes far longer. The more demos you make, the more new people emerge to say “Thanks, but that doesn’t solve my problem”. Rinse and repeat.

Then the demos need to be updated as OS and app feature change, which still doesn’t stop people finding years-old versions in dark corners of the internet and complaining they don’t work. I’ve stopped updating my large demo-bank for that reason. The time it would take robs of the time more usefully helping here.

I don’t think the computer literacy of a forum visitor is really a factor. Rather, general literacy—or rather an ability to articulate the problem at hand—is a factor. I’m not sure a facility with computers helps.

7

I think those are far more accurate obsevations than mine, @MartinBoycott-Brown. What I completely failed to get across was, no matter how many resources are written and curated, in a never-ending commitment to timeliness and relevance, those books or sites or whatever will never address enough how-to questions. It’s always better to ask in a forum, in the heat of the need, than elsewhere, and get pointed, up-to-date info – but that’s not my call. I’ll keep my peace.

1 Like
8

@PaulWalters Thank you, and I’m sure you are right in what you say.

@mwra Just to be clear, I was not thinking of demos at all. It occurred to me that it might be possible to cut and paste, or otherwise make available, some of the exchanges that had already taken place on the forums. I was not thinking of new material, just making old material more prominent. A way of saying “this is what someone asked and this is the reply they got”. I think it is something a lot of us already do in a way, in that we remember old posts, search them out, then put in a link saying “have a look at this”. There are already pinned posts in various places with useful stuff. Why not make it bit more organised and systematic? Some pinned posts with links to solutions to certain problems that would be useful to new users, all in a section for new users. Searching for material on a website can be quite a time sink.

Cheers!

9

@MartinBoycott-Brown - ah, sorry for misinterpreting. I don’t see any issue with more tagging/linking to useful things. Hopefully forum members can get involved and help share some of the documentation task. Indeed, I think it those closer to the problem can be better placed to judge what is most helpful. :slight_smile: