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?
