Best practices: Tiddler Naming

#1

Referring to: Best Practice: Tiddlywiki and Structure of Long Note

It seems having many tiddlers is unavoidable for creating lengthy texts like story books, novels, pamphlets, user guides, instruction manuals, essays, theses, course notes, …

So I would like to get opinions on naming tiddlers, while TW is very liberal in this regards, but we need some rules to be able to create structured linear texts instead of nonlinear, untidy texts

Some suggestions:

  • Tiddlers should be named consistently
  • Tiddler names should be short but descriptive (less than or equal to 25 characters)
  • Avoid special characters in the name (use A-za-z, 1-9, space)
  • Use capitals and underscores instead of periods or or slashes
  • Use date format ISO 8601: YYYYMMDD
  • Write down naming convention in data management plan

What other rules can be proposed here?

References

A TW Planning Department
Pick a date and insert it in a field
Best Practice: Variable Naming in WikiText Scripting
#2

@Mohammad another useful subject.

Personally I feel some guidance is needed but would be tempted to break most of your suggestions, when the application demands. I have toyed with dozens of tiddler naming methods and feel this is yet to mature,

  • Although I totally agree individual designers should have or

    • Write down naming convention in data management plan

  • However one simple rule is if it is not a friendly human readable name, such as one automatically generated with numbers, time/date etc… is to put it behind the system namespace “$:/” otherwise it interferes with the search.
  • To support the above rule, I believe we should add a field to selected system tiddlers called system-caption and only this additional field is also searched in the standard search. for example $:/TagManager could have the system-caption “Tag Manager”, all plugin makers can then keep all tiddlers they want behind the system namespace yet have their key tiddlers findable. In standard search it should appear as “Tag Manager” yet link to the system tiddler.

Why do I resist too much tiddler title determinism?
A unique feature of tiddlywiki is it places the title and is key to its standard data element “right at eye level”, I think this is one reason it is so successful. Yet a tiddler can be so many things but must also be unique, this is fantastic because it imposed an open structure.

As a result I think we should have “classes of titles” such as lets say a “general purpose note tiddler titles” may very well follow you rules above.

  • A rule I tend to stick to is to never use compound titles except with something like journal tiddlers, or because you are making use of a namespace eg $:/data/keyname/date and always keep the information elsewhere like in journal-date.
  • Obvious other ones already exist as documented in TiddlyWiki naming rules, Streams comes with a default rule tiddlername/datetimestamp (subtiddlers),
  • but tiddlername/subtiddlername is another
  • $:/namespace/tiddlername is another eg visibility temp and state tiddlers.
  • Interestingly we could also provide guidance when NOT to Name / create tiddlers but rather use a data tiddler / JSON to store info.

Inclosing I think some of your naming rules may also be a good guide to naming macros, templates, transcludable tiddlers, fieldnames etc…

There is also great potential for features and confusion now with the unrestricted fieldnames and if you use Unicode characters. I have a lot of tricks up my sleave there.

1 Like
#3

“Wiki” is, supposedly (me never having been in Hawaii), Hawaiian for “quick, fast”.

So anything that sniffs of heavy process/standards (“dogma”, just because I love the movie) seems counter-intuitive to me.

Not that I’m saying it is bad. If it helps you with your TiddlyWikis, absolutely do it.

Naming conventions/standards are especially useful in a multi-user/multi-contributor TiddlyWiki.

Personally, I prefer let things in a TiddlyWiki instance and everything about it evolve organically. Sure, there may be an initial plan, but any plan can quickly fly out the door.

That’s the great thing about any TiddlyWiki. It allows for agility, for quick refactoring, for incremental and iterative change/growth/etc.

I’m a big fan of Scott Ambler’s writing about Agile Modeling and Agile Documentation. (Well, Agile “Anything”.)

Do what is helpful, don’t waste time on what is detrimental comes to my mind when I soak in all of: The Principles of Agile Modeling (AM).

Regardless, a plethora of general best practices, some maybe applicable in some use cases, others better applicable in other use cases, might be cool. Maybe not as cool without use cases.

More cool, in my mind (a flipside to the same coin, I suppose), would be a list of the problems caused by certain things put in tiddler names. (A “good grief, don’t do that” list because such and such will happen, would be of huge value in my mind.)

Because the list of best practices you’ve listed so far, I would likely rarely (if ever) apply any of those.

  • I see them, maybe, as hurdles to creative writing process, stumbling blocks in a process of capturing as-of-yet fully defined/understood knowledge about something (the process of capturing/iterating being part of the defining/understanding)
  • Say I wanted to quickly keep a reminder to do something with some tiddler, why not put the reminder right in the title, even if it makes the title long? Expediency! Wiki!

Something like that.

#4

It’s an interesting question, @Mohammad, and my answer is that I don’t think there’s one best way to name tiddlers. It really depends on the (desired) structure of the information, which TW doesn’t really impose. The fact that the title is also a unique identifier does influence it.

I agree with you and @TW_Tones that naming conventions can be important, and if they are, they should be documented.

I think @TW_Tones makes a good point where slashes are appropriate in the system namespace. They can also indicate the directory locations of source files.

For a general “non-linear notebook” TW, a combination of structured titles and freeform titles can work fine. In my general wiki I have many tiddlers that were named freely and written with no particular structure in mind, and this works well for storing and finding those notes. There were also recipe tiddlers whose titles start with :P, and journal-type tiddlers starting with an ISO-style date. This wiki evolved in the way @Charlie_Veniot mentioned. It has never taken on much structure, but it is in continuous active use.

Lately, I’ve taken to using timestamps as a way to avoid having to come up with titles at all. This is most helpful in “thinking” mode, but such tiddlers often end up as transcluded subtiddlers, so even for sharing content they don’t always need a readable title.

As I’ve moved to viewing TiddlyWiki as a platform or framework for building applications, I’ve found fields doing more of the work that titles used to do. I initially resisted the idea of making “non-standard” tiddlers that require any special macros or view templates to read, but I’ve really embraced it now.

#5

Rules are meant to be broken

I just want add a little something because I think there can be a lack of subtlety when dealing with such broad subjects especially when they seem to relate to standards or guidance. The subtlety is there are multiple perspectives here;

  • A user designer or developer using a tiddly wiki for themselves
  • The same for a small local self supported audience
  • Publishing to a broader internet audience
  • Publishing to the tiddlywiki community solutions they can incorporate in their own wikis for any of the above purposes.

The reason I need to state this is because I dwell mostly in the last perspective and in many ways this is what talk.tiddlywiki.org is all about. Empowering members of the community to build simple to complex solutions.

The thing is if I publish methods, solutions and editions into the community for their reuse, if we choose to retain totally Laissez-faire tiddler naming standards the quality and reusability of what we publish will deteriorate. If I make a complex solution with little or no standards it will be hard to maintain and will cause a lot of unnecessary community activity and support needs.

So the point is we are all free to do what ever we want in tiddler naming standards but as soon as you start to make something publicly available, or you start to make claims, or encourage someone to make use, of new responsibilities arise. Be it personal or professional when we make things public or make claims to others we have obligations that match or exceed our rights.

So given these different perspectives, I believe we need to have well developed standards as guidance (no in any way enforced) that we can refer to when needed. This guidance can be developed by enthusiasts with a broad skills and deep interest and builds a resources for others to use without having to dig deep into the pros and cons of different approaches. Rules are meant to be broken but its nice to have good ones no one needs to break, so where ever you look the rules result in consistency.

Examples of breaking rules I see value with, in some cases

  • Actually naming tiddlers using prose in a wiki for building content from reusable content eg; advertising copy
  • Using tiddler names as fieldnames TiddlyWiki 5.2.0 prerelease discussion
  • Using Alternate Unicode alphabets for the readability of “system type” tiddlers but stay out of the standard search where users dwell.

In fact there is strong evidence that the development of standards has enabled out societies to achieve most of out successes from landing on the moon to the internet and smartphones (effectively computers in a pocket). I for one want tiddlywiki to succeed to “democratise software”, and it should be replete with optional but effective guidance/standards.

There are also parallels with art, creativity, the use of “Creative limitation” or “constraints” and standing on the shoulders of giant’s.

#6

Thank you for all these useful inputs and thoughts and ideas!

We learn from sharing ideas/opinions and specially from real world examples.

The reason I raised this question as @TW_Tones said is to distribute the TW to others like graduate students in a advanced math course! When other people use your TW, they should be able to simply use the it, find different materials in TW easily and can follow some linear path to learn a topic.

Please share your experiences and your opinion!

#7

I just want to point out, @Mohammad mentioned naming tiddlers, specifically not titling tiddlers.

My tiddlers can have many “names”, stored in

  • title
  • subtitle
  • uuid
  • caption
  • as well as arbitrary names chosen at the point of use somewhat akin to [[arbitrary name|actual title]].

And that’s all without the affordances of any “alias” plugin(s) or @pmario’s omnilink (is that the right name?)

This thread already has some lengthy posts referring to something that actually don’t refer to anything specific. I’m not trying to be pedantic just for pedancy’s sake, but something needs to be nailed down as “the topic” to make clear to newcomers what is being referred to.

#8

The name of the song is called 'Haddock’s Eyes '."
“Oh, that’s the name of the song, is it?” Alice said, trying to feel interested.
“No, you don’t understand,” the Knight said, looking a little vexed.
“That’s what the name is called . The name really is 'The Aged Aged Man '.”
“Then I ought to have said ‘That’s what the song is called’?” Alice corrected herself.
“No, you oughtn’t: that’s quite another thing! The song is called 'Ways And Means ': but that’s only what it’s called , you know!”
“Well, what is the song, then?” said Alice, who was by this time completely bewildered.
“I was coming to that,” the Knight said. “The song really is 'A-sitting On A Gate ': and the tune’s my own invention.”

-e

1 Like
#9

At the risk of sending the thread completely off topic…

Eric’s quote of Lewis Carroll’s piece is so apt – I had a mind to refer to Richard Feynman’s oft quoted story about knowing the name of a bird (in four or five languages) and still not knowing anything about the bird. But it was two lengthy and seemed a little obtuse if not too subtle.

Nice one -e! :nerd_face:

#10

Wow, I really like this idea! Too many system tiddlers are a bother to find, though being able to search them quickly via Ctrl+Shift+A helps.

In general, it would be interesting to consider how we can improve the documentation for important system tiddlers – most of what we find both in core and in plugins and other published tools contains a bunch of complicated wikitext with no description of what it’s for except the title, and that makes things harder than it needs to be for newbies (or even for experts looking at an aspect of TiddlyWiki they’ve never looked at before).

Maybe something kind of like a docstring, bundled right with the tiddler itself, in a different field or as a comment?

#11

Maybe something kind of like a docstring , bundled right with the tiddler itself, in a different field or as a comment?

This sounds interesting but on first read I could not understand it. I will return in the morning.

#12

I’ve wondered about that too. One approach would be to add a new field (like “_description”) to shadow tiddlers, and a default view template to display it, but perhaps it would be better to keep the description data in the “Internals” plugin so that it doesn’t make the core larger.

2 Likes
#13

@sobjornstad @TW_Tones

In addition to the list provided by the wikipedia article:

JavaScript supports (what I’ll call) “unassigned strings” – co-opted for…

"use strict"

The Groovy language also supports them co-opted by Katalon Studio to add comments to the runtime execution of Test Scripts.

'Open tiddlywiki.com in the browser'
WebUI.navigateToUrl('https://tiddlywiki.com/')
#14

I would use the more human readable YYYY-MM-DD.

#15

hmmm. The Internals plugin is part of all my wikis and it adds a functionality.

The _description info imo is not a functionality. It’s documentation from my point of view and may be it’s own plugin.

Parse date from tiddler title
#16

It’s named: “uni-link” plugin

I’m using the following fields

  • title
  • subtitle
  • caption
  • aliases
  • description
  • and sometime teaser

in combination with the “field-search” plugin.

Links to all my plugins can be found at: https://wikilabs.github.io/