I’d like to use this topic to post a new draft weekly (or so), until we get to something we think is fit for purpose.
Added some discussion about a “config note.” Added some verbiage to other topics. Added some more illustrations. (Learning a bit about how to prepare a .png.)
Hopefully we’ll spend some time today on the “config note” discussion, examples, use cases, etc.
The Hitchhiker’s Guide to Tinderbox.tbx (11.1 MB)
Thanks, @dmrogers. This is really impressive work. I’m curious, do you intend to export the content to HTML and make a site out of this, ala aTbRef? If so, I would be happy to help with crafting the export templates.
I hadn’t given any thought to exporting it as a web site, but wouldn’t be averse to the idea.
Thanks for the offer!
Let me cogitate on it. 
Now that’s a word you don’t hear….err…read often 
FWIW, I think you’ve done a great job of distilling years’ worth of meetups and demos into an accessible guide. Your writing is also excellent. And by “excellent” I mean concise and accessible.
It’s what old codgers do 
Now I wish I still had a Mac to have a look at this HHGTT…
Not especially productive this week. I wasn’t able to capture the discussion from last week’s meetup as the video just went up, so that’ll be in next week’s update.
I did try to take advantage of some low-hanging fruit by expanding on the advice to Begin With the End In Mind, adding a number of diverse applications with links from relevant forum threads. A work in progress, not complete.
I re-worked the name issue. Not the final word, I’m sure; but better, I think.
We can look over that material, but I think I’d also to spend some time on approaches to appearance settings.
The Hitchhiker’s Guide to Tinderbox.tbx (11.2 MB)
Well, I think Wittgenstein’s ladder is a useful way to defuse the naming‑conventions debate without pretending it has one universal winner.
In Tractatus 6.54, the ladder is a means of ascent, not a permanent part of the structure: you use it to get to a clearer view, and then you can (and should) throw it away once it has done its job. Applied here:
p_, t_, f_ can function as a ladder: a quick, low-friction way to keep infrastructure notes legible (“this is a Prototype”, “this is a Template”) before their internal model of Tinderbox’s built-in semantics (containers, prototypes, attributes, badges, outline context) is stable.So the emergent “best practice” might be stated in a Wittgenstein-friendly way:
Use naming conventions as scaffolding to reduce confusion until the document’s structure and Tinderbox’s native context cues do the work for you. Then be willing to refactor: keep the ladder only if it still pays rent.
That also ties back to “Begin With the End in Mind”: the end is not “I will always use prefixes”, but “I want my infrastructure to remain findable and unambiguous as the file grows.” Prefixes are one possible ladder toward that end, not the end itself.
In other words: the real advice is not “prefix everything” vs “never prefix”, but “recognize when you’re using a ladder, and don’t confuse the ladder with the building.”
Dave — thank you, and thanks to the whole community, for projects like the Hitchhiker’s Guide and for the meetup and forum discussions around it, which keep giving us substantial material and a recurring occasion to sharpen our thinking by working together on topics that can easily look “pretentious,” like best practices.
Because when we do our thinking openly, on stage, it becomes real work rather than drifting into a private language that only its inventor could understand — and therefore, in the end, no one.
In other words: the best practice is to craft a solution that works for us, while remaining at least plausible — and ideally genuinely usable and extensible — for others. Learning and using that shared lingua franca, in public rather than in private idiolects, is the spirit you’re starting to distill so invitingly with this Guide.
My thumbs‑up is both recognition and a request: let me travel along for a while.
Thank you.
Not to argue against your point but in addressing rationale for naming conventions some important aspects were omitted. The naming conventions used arose not for simple labelling.
Which of these notes is a prototype: one, both, neither?
OK, in Outline view we can see:
It is both! But what if only one were a prototype, how do we tell which it is. OK, lets make only one a prototype:
Now in the map we want to link a new ‘note B’ to the non-prototype ‘a note’, but whether dragging a link manually or making a zip-style text link we can’t tell the correct one. Plus if linking by title ($Name) alone, and the app encounters a duplicate name it auto-selects the first by outline order ($OutlineOrder). Plus, here, as both notes are at root, their $Path is the same.
Separately, a deliberate, unique and easily-convention-remembered name is useful for code to ensure the correct target can be called easily to mind without mis-addressing the target.
If doing documentation work using a note named for common term invariable results in a duplicate use of a name for a prototype and a non-prototype and thus hilarity ensues.
If instructing others, especially new starters, or in sharing code (e.g. TBX, libraries, etc.) naming conventions make instruction and description much easier. Plus, for the likes of libraries, the chance of naming collision is avoided. If your document has prototype ‘Event’ and you add a library that uses a prototype called ‘Event’ but with different customisation, there is scope for instant confusion and frustration.
So naming conventions do have a long-term purpose!
Given that generally naming conventions are for notes whose purpose is use ‘behind the curtain’ a name that offends aesthetics is generally never seen in views so the eye is likely not offended.
I do wonder about re-factoring later as there is zero benefit, other than perhaps aesthetic, but in a mature doc there is often lots of incremental complexity the user often failed to record (the app better supports the latter these days) so ‘just’ re-factoring can be heard even for an experience user.
Thus I’d stress no one has to use such naming conventions, and if using them stop to consider their role in your doc. If not needed, don’t use. The latter links to those who take a last-century dataset where everything ever wanted has to be defined before adding content. That isn’t needed.
I think this circles back to a point I’d sent in to @dmrogers of the problem of users embracing process (the steps described or video-ed) rather than the *concept illustrated. So “Always name you prototypes with a asterisk prefix” is not helpful. But, “naming prototypes with names unlikely to be used for general content and which are likely unique in the TBX” is. Person X might use a asterisk prefix, person Y a ‘p’ prefix and person Z none. X and Y can easily understand each other’s code, Z’s document less so.
For the same reason some may look down on naming a List-type attribute ‘PartList’ or ‘Parts’ rather than the simpler ‘part’. But in a years time will you remember what $part is for or its data type. Now, if you don’t use action code at all—or infrequently—you’ll do fine with ‘part’.
On balance, I think scaffolding is generally useful and removing just for issues of purity (visual or otherwise) is essentially a personal aesthetic choice rather than one of practicality. I think where people take against naming conventions is when presented with someone else’s convention and which differ from ours as we instinctively know that to be wrong and unhelpful our own convention, obviously is the correct one 
Sorry, I can’t make the meet today but the above might a useful topic for discussion—how much scaffolding is useful?
Fascinating discussion, and the feedback is very appreciated.
There is, perhaps, a broader, underlying issue that is exposed by this debate, and perhaps one that deserves greater examination/discussion in the “General Guidance” container.
Early last week a somewhat familiar question was posed. I tried to offer what I felt was a helpful reply to a difficult question, and I think it is indicative of the broader issue.
We have had many discussions about the expectations that new users’ previous experience impose on Tinderbox. “It’s an outliner!” (Mind-mapper, chart generator, timeline plotter, database, etc.) These, in nearly every case, are impediments to early understanding and productive use of Tinderbox, as expectations inevitably bump into confounding behaviors that can lead to frustration or misunderstanding.
I’m more comfortable with Eastern philosophy, though I’m not unfamiliar with Wittgenstein, but I think you, @andreus, make the case that a philosophical approach is valuable when encountering Tinderbox for the first time. Or, perhaps more importantly, after some early positive experiences with the app, where one’s prejudices and misconceptions may have already been validated.
Perhaps I should have kind of modeled my approach on Zen and the Art of Motorcycle Maintenance, rather than The Hitchhiker’s Guide to the Galaxy. I chose the latter because I wanted the document to be approachable, light-hearted, but still worthwhile. But it seems like Tinderbox does demand a more philosophical approach, at least at first, to wit: Beginner’s mind.
This relates to the question of $Name as its seemingly mundane nature may conceal a value and importance in the user’s relationship with the document and how that facilitates the goals or objectives of the document itself.
To me, it has often felt as though $Text was the premiere attribute and I often regarded $Name as kind of a necessary distraction, something I had to dispense with quickly so I could get to the important attribute, $Text.
Truthfully, I still do not understand the objections of the people view a prefix notation as somehow polluting something. I’m not saying they’re wrong, I’m saying there’s a gap in my understanding, because they seem to appreciate some additional value in a “pure” (unpolluted?) $Name.
But it is evidence of the importance of $Name, and, to my knowledge, that has not been a topic of much discussion, apart from this sort of, to me, stylistic debate. And it makes me wonder if the value or importance of $Name deserves a greater examination in a document that is intended to illuminate some of the more distant corners of Tinderbox?
Not that I want to get into analysis paralysis, or a “gumption trap,” but it just feels like I ought to be able to articulate the value or importance of $Name more clearly than just the question of whether or not to use prefixes, and whether or not they represent some sort of crutch or artless use of Tinderbox.
How do we write meaningful $Names? What is their value within the document, other than perhaps as a label for the contents of $Text?
Seems pretty fundamental. Am I wrong, or getting off track?
Two quick thoughts re $name, it the note’s title. If a visible label like “pPerson” is offensive to the eye, consider a Display Expression, that sets $DisplayName, the visible on-screen render of $Name.
So imagine a prototype like so:
Now, that offending use of a prefix is banished, via $DisplayName:
Note: above, the actual $Name is unchanged, only the screen label is altered
Also, whilst making a link via an action might not be task #1 on first use, the most oft-used simple form of describing a link target is by using its $Name. Thus un context, something like “*Company”, “pPart” is likely easier to recall than trying to remember if a prototype is called a “A part” “The part”, Part" or “part” ($Name is case-sensitive in code use). Bear in mind that prototypes and templates are most often set from a menu or via code, so the pragmatist should choose something that will not later confuse them. But, there is, and cannot be, single ‘right’ answer here as domain, task, learning style, etc., vary by person. So, scope for all of us to feel judged as doing things wrongly.
Reflection: we don’t hate the people in the next village over because they wear their hats a different way to us, we hate them because they don’t wear them the only right, civilised, way like we do in our village. T’was ever thus. Legislating taste is nigh on impossible.
$Name & $Text also cause confusion for some coming to Tinderbox from other note taking tool. In some outliners, the title & text are the same thing (i.e. in Tinderbox terms $Name==Text). In some outliners (e.g. OmniOutliner) the title is the first part (paragraph?) of the note label. And so on, depending on how wide one’s purview of note-taking there is no right way. In the case of Tinderbox, a note object has a discrete title ($Name) and body text ($Title). A tell here is seeing some new users having improbably long note $Name values as they assume what you see ‘is’ the note. For others, $Text not visible in a map icon might as well not existing. this isn’t wrong: it simply reflects expectation build on past experience.
I think that for those coming from simple note taking (note = one text string), the $Name does many basic things, like be the visible textual label, but in Tinderbox it is essentially just the label. Whether the label is repeated as the beginning of $Text is personal stylistic choice. Having worked on other’s data for so many decades, my notion of ‘normal’ is somewhat blurred.
I think we sometimes delude ourselves that we don’t mind that others do things differently from us (e.g. note naming). We smile through gritted teeth as, silently, we know their way is just … well, WRONG! This is the minefield we navigate when trying to help [sic] people starting out with ideas of best useful practice, as the norms for that clearly don’t have a single set of answers.
Brief reply as it’s moments from time to call Mom and then we have the meetup, where you will be missed.
But I take your point, and have no argument with any of it. But this discussion has prompted this question in my mind about the role of $Name and how we might think about that most productively. Perhaps I’m barking up the wrong tree, but I’m unwilling to let it go just yet.
I was reading this, in my ind I was preparing a similar response to the one that @mwra wrote. Summary thoughts, naming conventions and prefixes are NOT just about aesthetics, i.e., visual appeals, they are usefule for:
No, I’m no Buddha, but I would like to impart an idea—there is such a thing as “wisdom based learning/teaching”.
Wisdom is the integrated capacity—developed through lived and learned experience—to perceive reality clearly, discern what matters most, and act in ways that serve long-term flourishing, especially in the presence of uncertainty, complexity, and moral consequence.*
After years of hard fought experience the teacher/friend/community member learns that engaging in certain practices makes things easier immediately not to mention down the rode as complexity grows. I can’t tell you how many times @mwra in my early days with Tinderbox (my words not his exactly but the spirit is there) “shut up and just let me show you, you may not ‘understand’ now, but you will. Do this an you’ll save yourself a $@##%$ ton of angst and anxiety in the future.” Again, @mwra was immensely more polite and patient that these words suggest, but that was the general gist.
We are all on our own path and we will all find our own way to navigate it, but through hard fight experience many of us have found ways of doing things that ore more effective and efficient that others, even if those ways may not be immediately explainable and understandable.
The next part of the lessson is, even for the “expert,” you need to be ready at any time to let go of your hard fought learned method when you find a new approach that works and helps you. This is really hard to do. I’ve had some methods where I litterly spent years “perfecting them” but once I learned “the better way” I had to drop them, learn and refine the new way, and move on. Initially, dropping the old mehtods was really hard because I focused on the “lost time” but I’ve since learned that there is little benefit wasting effort focussing on the past like this…take the new method, refactor and move on. A great example of this is my use of $OnVisit. My files were getting so large and so complex that $Rules and $Edicts no longer served me, as cool as near real-time updates where they did more “harm”, i.e., sluggish performance, than “good.” So I refactors, learned some new behaviors and saved my ability to continue to use Tinderbox.
Again, we’ll each find our own path as we individually evolve. Some party thoughts:
“Writing is the greatest of human inventions, binding together those who are far apart in time and space.” — Isaac Asimov
“If I have seen further it is by standing on the shoulders of giants.” — Isaac Newton
As you think about the use of $Name, it is important to remember context.. $Name is extremely context dependent, e.g., if you are writing and your using names as heading (chapters, parts, section heads), using $Name to distinguish research notes (.e., terms, stats references), etc. I find it really helpful to keep things fungible.
Also, I think it is worthwhile to remind people/introduce the idea of $ShortTitle, a user generate attribute convention that I made that hold the $Name sans an prefix or suffix that you may have uses, e.g. $Name=“Trm- Wisdom” and $ShortTitle=“Wisdom”. This way, you can have the functional benefit of the prefix and sufix for TBX operations and then use the pure name, i.e., $ShortTitle, in your output. It just take a little bit of RegEx in your action code to strip out the pattern of your prefix or suffix pattern to automatically populate $ShortTitle.
Any chance someone could export it to pdf and html? I’m still deciding whether to purchase tinderbox and I feel like this guide could help me decide better. Thanks!
At @dmrogers request, I’m re-posting some thoughts I sent as a DM.
Why originally a private msg? I simply didn’t want to make another long post and which might discourage more folk to contribute to the thread. Anyway, with some very light editing for sense (including changing second-person terms to third person so as to be less direct), …
So, we often describe what Tinderbox does, or does not do, but what we’re pushing on here is the sense to which we are essentially the victims of our past experience, as it shapes our norms’ as to what is expected right.
I think there are two overlapping issues here:
This digs into the under-discussed aspect of what do we expect a note’s title (forget the attribute’s name for a moment) to tell us, in-app?
A linked aspect we might also check, is why are we trying Tinderbox? Is it replacing another app and if so, what did the other a not do for us?
I note these as all too often we get new joiner’s moaning that Tinderbox works wrongly as it not like [app they know]. So are they escaping a bad experience or looking for more capability? The answer leads to a different way to help them (e.g. in @dmrogers’s HHGTT).
We also overlook different domains’ perspective. In some of the humanities, argumentation is expected to be a visible part of the structure (this supports…, this opposes …, etc.) but that not a universal. Of course, experience is again a dis-enabler here as it colours our norms. If I expect very visible argumentation structure, then that not being front and centre of a how-to may be perplexing—and vice-versa.
I’m coming to see most of [us] are quite blind to this unintentional parochialism. Even knowing there is difference doesn’t stop us naturally reaching for ‘our’ perspective when explaining things: q.v. all the recent discussion of name prefixes. I think much of any to-and-fro discussion is people getting discomforted by exposure to others norms.
An overlooked factor is the subtle effect of a raft of apps in the last decade using Wiki-style linking where the note title—external file or internal text—is used for linking and as the anchor text. This has its own subtle constraints on naming as what might make a clear note title may look odd auto-inserted as anchor text inline in $Text. Using zip-method linking for typing holds an echo of that approach. There’s no ‘wrong’ in that, merely an echo of constraints imported with a technique acquired we an inflow of users who cut their teeth in such an environment.
I still tend to use drag-drop for link creation. My documents often have duplicate $Name values (for valid content reasons) so I consider naming far more in the context of its effect on export (sharing with others) than for internal use (apart from problematic characters).
Map-centric (-only) use can unwittingly add a constraint that what isn’t displayed is not ‘seen’ so may result in longer titles or more displayed $Text. Some people are definitely more visual literal (info must be visible) whereas others are happy to treat notes and their names as a proxy pointer to greater info ‘hidden’ in text.
Prior experience in other notes taking apps and the subset of Tinderbox views/features use are as likely to affect $Name formulation as any more philosophical choice (nor is there an implicit zero-sum choice).
Bottom line: I’ve observed no single common note-naming approach, nor would expect such in a very open-ended tool. But whether the $Name† is repeated in $Text or not, Tinderbox expects a note to have a title and optionally further body text.
†. Yes, I realise it is possible to have a note with no title‡, but does have a $Name which is "". Howe er the places where that is desirable are too niche to be germane to the wider topic.
‡. All notes have a (unique) ID ($ID) within the document so missing or ambiguous $Name or $Path can be routed around. But again, an edge case.
[Apologies to all, I mis-posted my post above to the wrong thread, now corrected]
It’s possible, maybe even likely. But I don’t feel as though it’s really ready for that just yet. But I think that’s a matter of weeks, not months, until it is.
In the interim you can certainly use Tinderbox in the demo mode. You can only create a limited number of notes, but you can open a file of any size, including this one, and poke around. I’m sure someone will correct me if I’m mistaken on that.
As notes with no title (where $Name is "") got touched on above, you can ‘hide’ note titles in map and hyperbolic views by setting $NameColor="transparent";. This allows the note to have a $Name value but for the title not to be seen in the view pane. But, note that this trick works only for map and hyperbolic view, not other views.
Below, we have notes ‘Note A’ and ‘Note B’. The Note B’s $NameColor has been set to transparent:
This is a technique @beck used to manage using Map links as illustration rather than their customary hypertextual role as demonstrated in, I believe, this video.
And since the tab is open and I’m already here, this, more recent, video is also fascinating and a rich discussion that I need to mine for the guide.
I began watching to see if I could observe anything related to a specific sort of practice or approach to $Name. She seems to prefer map view, and I’d say she follows a “thoughtful/intentional” approach. They’re simple or succinct, but they seem clear in the context. Where additional information may be useful, she uses longer names.
I think Map view does kind of require, or perhaps just prompt, a somewhat different approach.
I hesitate to think about the Information City View and how that might influence one’s approach to naming, but it probably bears some examination.
Anyone interested in Tinderbox is well served to search YouTube for Beck Tench’s videos.
Does there have to to be an ‘approach’ for naming. I say this not to disparage [naming method] but in foregrounding such implicit rules is there not a danger in giving new users one more friction to getting started.
So, if your teacher, or the strict process you are following demands a particular rubric, follow it. If not, just dive in. You’ll make mistakes and Tinderbox is forgiving. Trying to follow ‘best practice’ helps less if it’s not clear why. Mapping theological heresies: fine-grained process. Making inventory of the cupboard under the stare: just write stuff down. There is no single right answer.
Premature application of process sits close to restrictive software design: “do only these things in this precise order or you get … nothing”. Tinderbox is not such an app so I’m pained when I see the first thing people try is highly restrictive. Not least, because what attracted them was some aspect of a demo or video likely isn’t actually part of the process they’ll now slavishly copy. Sometimes it is worth colouring outside the lines just to get a feel for why the lines are there—especially if life to date has been strict adherence to rules.
