I am starting an ambitious complex project, long in planning. I will have several key collaborators. I understand the issues of version control and will address those separately, initially by enforcing a one-at-a-time rule.
This question is more basic. I’ll be starting from scratch. I’d like hints on best practices to avoid problems simply moving from computer to computer. I know, for instance that my preferred fonts will not be on anyone else’s machine, so I may want to consider using the built in fonts. I’ve already been bitten by files that started in Dark Mode, so am avoiding that, enforcing Light Mode. I recall in an old project, problems with custom badges, and I think we retrieved external code. Is there a simple list of best practices to keep everything internal to the file?
Hi. I think the best basic advice is is you are going to share, especially with users less familiar with the app, don’t customise except where you need to. Most guidance available to others describes the plain vanilla app so the less your docs look like that the harder it may be for new users to get up to speed.
Don’t overlook affordances of the Tinderbox Application Support folders. For instance, the badges used in your previous projects can be shared ideally as folder copied to each collaborator to install in their own badges folder.
Code can be written to auto-configure attributes but if the key documents(s)m are under constant evolution consider whether such is just a vector for another axis of misconfiguration.
It may seem appealing to try and do everything in one document, e.g. content and version control, but you might have a less chaotic result is if you get collaborator’s docs to check a version control link , q.v. here (Backstage forum link).
A common issue seen here is folk burying them selves in ever more code without asking which code gives meaningful return on effort.
Not all elements of a TB are (code) explorable. For instance, the number/view-type of tabs. So it is worth first considering what needs versioning and why. In a multi-/discrete-user scenario, knowing something is not current is but a small part of the challenge. My hunch is that in this context less (code) is more.
The goal of every collaborator other than myself is limited to working with text in notes, adding/editing links, and linking to Bookends. So the only folks worrying about the code will be you and me.
Looking at the built-in fonts makes me commit to installing my fonts on my collaborator’s machine. Not a fan of Hoefler. Its likely that collaborators won’t exceed 3.
A log of some sort is important – the simpler the better. For long, complex projects there will always be numerous moving parts, no matter the best intention of keeping everything simple. Moving parts means forgetting – who did what, when. It will be useful for keeping sanity in hand. Don’t rely on the machine to log; the best (i.e., Tinderbox) journals are human.
Understood, that makes things easier. I’d suggest keeping a master change log (archive) outside the main working TBXs. Implementation notes would start in working docs and copy (or migrate) to the master archive. This avoids bloat in the master docs.
If things like MCP AI integration are used, keeping admin/version material also keeps it out of the analysed content too.