Before I get too far along in this effort, I’ll upload this draft and ask for some feedback.
Hopefully this is on the right track.
(Every time I try to finish this, I think of something else. But please know that I do hope we can include a link to the relevant article in atbref for each best practice, if appropriate. But I think those links are fairly dynamic with the revisions of atbref, so that might be problematic?)
Dave
Best Practices.tbx (4.9 MB)
Wow, this is a great start, @dmrogers. I like the direction that you’ve taken with this best practices Tinderbox.
Hi Dave,
I think there’s some solid advice in here, particularly when you’re starting out - it’s such an open-ended tool there’s hardly a single right way, but there are lots of wrong ways. I’m still learning them!
I have to say something I didn’t know was the separators are also containers so that has already improved my quality of live life overnight.
Your theme was quite pleasant to behold as well, it’s always nice to see work beyond the defaults in this space.
edit: saddened @mwra’s quote preserves my original typo for eternity
We agree, Paul. There’s an attribute for “level,” but I haven’t populated it yet with anything. The idea would be agents called “Basic,” “Intermediate” and “Advanced” would gather the relevant notes.
There will also be some front matter on how the document is put together, how to use Tabs or Search, and so on. I think, ultimately, we’d like the document to be customizable for the user so they could apply their own “theme” to its appearance, perhaps an opportunity to demonstrate Stamps?
We’re just getting started, but part of the inspiration for me is the old Mac Secrets book(s), which were such a trove of useful information. They were also tomes, so I think we may need to keep an eye on size.
“We” are “the community.” There is no intended “in-group.”
I suppose I’m the guy who’s sort of “responsible” for this, (Because when “everyone” is, then effectively “no one” is.) but the idea met with some enthusiasm at the meetup and the intention is for anyone who has an idea or an insight to contribute, please offer it either here or at a weekly meetup.
I’ve asked that we use the first 10 minutes of each meetup to discuss the current draft of the document and offer suggestions for improvement. Those can include new practices or tips, revisions to the structure, edits to the text and so on. Say what you will about Zoom, but these face-to-face, real-time interactions can be productive in ways that forum threads aren’t always.
At some point, I imagine this project may make a good example for using a version control system like GIT, but I think at least I’m shooting for a “minimum viable product” for the first “release.” Something that is immediately useful, but doesn’t necessarily contain an encyclopedic amount of content.
I have no experience with things like GIT, so I’m not going to lean into that.
This doesn’t replace aTbRef, or the Forum, nor is it intended to replicate them. It’s just a document a user can download and get some immediate insights on using Tinderbox, with some of the ideas being represented or demonstrated within the document itself. As I’m by no means an expert or even familiar with every dimension of Tinderbox, this will require a group effort.
This wrinkle is an interesting one. My understanding is that separators were to be an Outline-only feature, much in the way adornments are Map-only. But part of their heritage, as a special form of note, was that they (accidentally) retained the ability to nest other notes, i.e. act as a container. By the time this came to light, users lobbied to keep this. Thus came the by-product of ‘hiding’ branches of the outline in other views by making a container into a separator. Documented, but sometimes overlooked is that even an agent can be a separator.
I’ll admit this is an area where aTbRef, deliberately, chose not to tread. Why? Because the way the sheer range of tool combinations make a ‘right’ way hard to pick. Plus changes to the OS and app often render older solutions unnecessary or sub-par. A linked challenge with ‘getting started’ is one of ‘to what end?’. Person A’s “must have” is Person’s B’s “do not need”, and Person C, etc. Each doesn’t thank the writer for making them wade through things they reflexively ‘know’ they don’t want (or so I’ve observed over several decades of this)
Ideally, new Tinderbox folk would learn a bit about generalities of the app first, but that’s seemingly now a very old-fashioned approach. Instead, we want the thing we just saw (probably doing something quite different in nature) and we want it NOW! Woe betide anyone wasting our time on how the basics work, that’s just wasting our time.
So, it’s hard giving basic guidance, because even what we each consider ‘the basics’ is subjective and reflects both one’s prior experience of apps and domains of study/experience. Explaining to someone who ‘just’ wants a simple to-do setup that they ought to take a moment to understand the basics of Tinderbox prototypes can be a hard sell.
I thank @dmrogers for even stepping into this ground … and giving us something to critique. I note the comment above about ‘best’ practice and implied values—even if unintended. One possible approach might be to map types of task to features/techniques used. This might provide a looser binding than best practice. Or, simply describe building block techniques with why/for what they might be useful and other features/techniques upon which the rely. I sense the draft doc is close to the later. But, perhaps a Sisyphean task.
I’ve certainly been hoisted on the petard of “there’s interest in …”. It transpires that we generally say “Yes” to the offer of free stuff that we then look over once discard, and ask for more free stuff. The supply side can’t keep up. Just this morning I want looking through my old 5 demo set of TBXs and the never-completed v6 rewrites—I simply ran out of time and then many things were out of date.
I would observe that worked examples (e.g. a topic with intermediate and final example TBXs) are always popular in concept and rarely used (or commented on if used). In hindsight a really low return on the creative effort expended.
None of this should put you off, but it might help steer you away from known rocky shores.
I very much agree. I reflect on the years of meetups where I/we reviewed templates and action code and the feedback was “great–but not for me” or “you’ve made it too complex”. The former after requiring time for people to understand the need, and the later often been so VERY true as a result of unexplained/often unknown assumptions and muscle memory.
Context if everything. A couple of the most in important context questions, before you even touch the app is “what” and “why”. What are you trying to accomplish? What do you want to achieve “in the end”? Why do you want this?
I can be surprisingly difficult to really understand and refine one’s objectives.
I think I’ve been unclear.
What at least I have in mind is a Tinderbox document, not a book, emphatically not a “series of small guidebooks,” and not a web site. If anyone wants to do those things, by all means, please do so.
It will not be a “user manual,” nor a “reference manual.” In the “Read the literature” note, there will be links to things already written, like aTbRef and Help in the app, Mark’s book(s).
The audience will be people who are already using Tinderbox. The intention is to be accessible to “beginners,” (is “novice users” better?) and useful to Tinderbox users of any level of experience.
The purpose of the document is to aid the user in achieving success more quickly by avoiding pitfalls, leveraging the knowledge and wisdom of more experienced users, or taking advantage of unfamiliar features. Is that an impossible goal?
The document isn’t intended to market Tinderbox. It’s not intended to answer anyone asking “Why should I use Tinderbox?” I don’t know why anyone should use Tinderbox, I only know why I do.
If using the term “best practices,” gets anyone’s knickers in a twist because of implied value judgments, then we can just call it “Tips and Tricks.” When I was a ham radio operator, QST magazine had a “Hint and Kinks” column. It’s, hopefully, just some accumulated wisdom from the community that might be useful in trying to get something done using Tinderbox.
It’s not intended to be rigidly prescriptive, but how many times have we heard, “Turn off smart quotes,” when people are struggling with Action Code? Maybe that’s irrelevant now. Maybe Action Code is automatically rendered as “Code” and straight quotes are built-in. But we can run code in $Text now, no? So maybe it’s not irrelevant? These are things that might be helpful to know. Clearly, I don’t know.
Will it be undying prose? Will it undergo constant revision? Will it be relevant in years to come? Who knows? It’s barely gotten started and we’re asking that? Maybe we should wait until we know those answers.
This isn’t going to make Tinderbox “easy” for anyone who finds it “too complicated.” It isn’t going to answer every question, or point out every potential pitfall. But, hopefully, it’ll spare some people from making some mistakes.
I phrased it in the meetup as a “modest proposal.” I have no ego invested in this, I’m happy to forget the whole thing if what’s going to go on here is to point out all the ways it’s somehow deficient, inadequate, not fit for purpose. Or deciding before we’ve ever released anything that the audience won’t like it, find it useful or appreciate the effort.
I don’t know. I thought it’d be kind of fun. “The Hitchhiker’s Guide to Tinderbox,” was one way I was thinking of it. Throwing in random references to things like the Colossal Cave, and some other pop culture references.
But, geez, what a buzz-kill.
I’d reiterate my thanks for you taking taking a run at this, and your example of the issue of quote characters in $Text and action code in Text (whether to run, store or simply describe examples) does offer a good angle for this advice. The experience and expertise you are offering should help engaged users to understand some problems they have, and to avoid they might have. I think that’s a laudable goal.
I think it will be tons of fun, and also very useful!
I agree…we certainly can make “progress” with this effort.