Can Hierarchical Navigation Benefit TW Documentation?

[pmario]

@CodaCoder

But that’s not how breadcrumbs are used on the web. Nobody does it like that!

Mozilla does: <td>: The Table Data Cell element - HTML: HyperText Markup Language | MDN

[CodaCoder]

@pmario

Mozilla does:

Sorry, you misunderstand me. Those bold points are arguments against my point.

[TW_Tones]

@pmario

I think that’s a bit OT here.

Yes and no

@TW_Tones

the keywords could promote master tiddlers that expose a story or heirachy you could use to take a curated journey.

My point being where does a story start?

[Mario]

@CodaCoder

Sorry, you misunderstand me. Those bold points are arguments against my point.

OK. … I did move the posts, because some of your points made at:

Can Hierarchical Breadcrumbs Benefit TW Documentation

Aside: Maybe this belongs on the other thread but that thread is already too lengthy (IMO) to foster clarity for reasoned discussion. So… To be clear, we are not truly talking about breadcrumbs, but rather something like “predefined pathways through a chosen topic chosen from among many”. Breadcrumbs, on the other hand, should show the path taken to arrive at a given point (with no preconceived idea as to its logical/hierarchical placement within the forest as whole). I’d much prefer to not …

highly relate to my post here in this thread

Can Hierarchical Breadcrumbs Benefit TW Documentation

That’s the usecase, that I mainly wanted to discuss with this thread and that I want to try to improve with a work in progress PR at GH. If users are new to a topic I think it’s important to provide the hierarchical context a tiddler is in. Once users are familiar with the whole system, this information will be less inportant for the understanding, but it can be a “quality of live” improvement, because it provides a nice and fast way for “linked navigation” That’s also a main goal of the PR m…

[CodaCoder]

@pmario

All your quotes miss references

This is not a scientific or academic discussion, treatise, whitepaper, or any other kind of published paper.

Perhaps you’d prefer I signed off with…

“Just some thoughts”

which I find tedious and unnecessary.

[Scott_Sauyet]

@TW_Tones

Breadcrumbs will be from a root to a node only in highly structured environments,

I felt like that is what we were discussing here. For instance, in TW-com, we have all sorts of documentation on Filters. A fair chunk of it forms a hierarchy. The clickable railroad diagrams are one beautiful way to express that hierarchy. Breadcrumbs were brought up as a more general way to do the same thing, to express hierarchies that exist among subsets of the tiddlers.

@TW_Tones

I have use large mainframe systems that use this. They usually demand you follow the structured path to get the job done, and as a result the path or story is equivalent to breadcrumbs.

I think of those as a different sort of beast. Those are usually expressed as a fixed set of steps, with the current step highlighted, and the main navigation involves previous / next controls. Breadcrumbs allow direct access to any of the levels above the current one in the hierarchy.

@TW_Tones

The metaphor of breadcrumbs does come from Hansel and Gretel and represents a trail you have traveled and allows you to return from where you came.

• Although it is commonly misused

As I said ealier, I think that ship has sailed. “Breadcrumbs”, like “file”, “folder”, and “desktop” are analogies to commonly-recognized concepts, but are never perfectly correlated. “Breadcrumbs”, like their fairy-tale counterparts, help you navigate your way back. But they don’t track the entire path you took, and they also offer jumps higher back that Hansel and Gretel would much have appreciated!

@TW_Tones

I do like the idea of stories represented like @pmario illustrated but I see, in some cases, the potential for too much information to handle easily and by default on tiddlers.

That’s a very serious concern for large wikis or ones with many interconnections. I think @pmario’s story metaphor is great for smaller chunks, without too many overlapping paths. But it breaks down when there are too many links.

@TW_Tones

There is also an innate human skill I refer to as “Trail memory” I have mentioned before that we can leverage.

Yes. It is significantly enhanced by a visual metaphor, such as a tree navigation, a connections map, or breadcrumbs. And some people have stronger senses of this than others, as we’ve discussed here before.

@TW_Tones

@Scott_Sauyet

how do you place the various elements?

• My notes above highlight that the answer to this depends which navigational model you are using, and all are possible in TiddlyWiki.

Note that my question to @pmario was specifically about his proposal, an attempt to show that it’s likely to run into scalability problems. Although I still have some ideas about it, I ran into this wall with my Nearest Neightbors demo. Some day I will try to get back to that, to build a graphical view, but it’s extremely challenging to find a good way to this.

@pmario

If users are new to a topic I think it’s important to provide the hierarchical context a tiddler is in. Once users are familiar with the whole system, this information will be less inportant for the understanding, but it can be a “quality of live” improvement, because it provides a nice and fast way for “linked navigation”

I think there’s some problem with “the hierarchical context a tiddler is in”. When we have a single such context, there seem to be a number of good options. But nothing seems to work well when there are many.

@pmario

That’s right. IMO a story-tiddler can contain meta text, eg: a summary and one or more configurations that allow it to “tell a story”.

As I realized when writing my WizardNav plugin, tag tiddlers are a pretty powerful way to capture such information.

@CodaCoder

To be clear, we are not truly talking about breadcrumbs, but rather something like “predefined pathways through a chosen topic chosen from among many”.

I’m trying to steer back to “breadcrumbs” as used on many websites. This is what I think would help with documentation on TW-com. They’re not perfect, and if tiddlers really should show in several hierarchies, it can get ugly. But I think overall it would be a big help.

@CodaCoder

I’d much prefer to not use the term “breadcrumbs” for the “wrong thing” because, should we decide later to offer something truly breadcrumb-like, the term will already have been misapplied leaving us struggling to find another.

Absolutely.

@CodaCoder

Let’s please call them TRACKS (or something).

Yes, or stories, pathways, etc.

But rather than that, let’s go back to discussing more standard breadcrumbs for hierarchies.

@CodaCoder

But that’s not how breadcrumbs are used on the web. Nobody does it like that!

Typically, TiddlyWiki does not encapsulate a conventional website structure.

But it does borrow a lot from the standard web (think links, tabs, cards, icons, etc.) When we can reuse conventional structures in a familiar way, we make it easier to use.

@CodaCoder

But this is only meant for documentation tiddlers.

Good point. But once it’s used there, like everything else in TiddlyWiki, it will be used and incorporated elsewhere. Again, it’s the term I’m proposing to change, not the mechanism.

And I’m suggesting much the opposite: let’s find a mechanism to match the term. We already have opt-in TOC functionality; let’s add opt-in breadcrumb functionality. But here I mean web-standard breadcrumbs, and not a full story/pathway/tracks/trail feature.

It sounds fairly simple to implement, so long as tiddlers live only in one hierarchy. (Just give each tiddler that live in a hierarchy a field that notes its parent, traverse the chain until one doesn’t have a parent, reverse the list and display it as a list of links, in whatever pretty format you like. Or – only a little harder – express it by having tiddlers list their children.) But as soon as any individual tiddler has multiple hierarchies, it gets much uglier.

[Alvaro]

The breadcumb navigation would be great improvement in documentation.

Some thoughts:

• The term “breadcumb” does reference to trail/track/ …/navigation/path. I would also be more inclined to use one of the referenced terms.
• I have doubts about: how/where we would want to display it. It shows new questions about how it could be implemented.
• Would the use of this navigation be stored in any place? Someone might want to move foward/backward, althought it would be too work to implement it.

There are many points to close before to start.

While I was reading I thought in possible uses of the breadcrumb macro.

• The macro to use in the body or outside of body (like the tags wrapper)
• Hint about the breadcrumb or not.
  Example: Navigation: breadcrumb 1 > breadcrumb 1 If the term for this define the breadcrumb menu is Navigation

Another idea, and more complex, would be a kind of wizzard/navigator (tiddler) for the documentation with its breadcrumb menus and one or more stories to facilitate the navigation.

[TW_Tones]

@Scott_Sauyet

I felt like that is what we were discussing here. For instance, in TW-com, we have all sorts of documentation on Filters. A fair chunk of it forms a hierarchy.

• I understand some are focused, not on breadcrumbs, and more on hierarchies, but TiddlyWiki needs to cater also for non-linear, multiple stories and journeys and other representations. You could say my first answer to the OT is;

Can Hierarchical Breadcrumbs Benefit TW Documentation?

• Yes they can, but they are insufficient

@Scott_Sauyet

“Breadcrumbs”, like “file”, “folder”, and “desktop” are analogies to commonly-recognized concepts, but are never perfectly correlated. “Breadcrumbs”, like their fairy-tale counterparts, help you navigate your way back. But they don’t track the entire path you took, and they also offer jumps higher back that Hansel and Gretel would much have appreciated!

• To me, Breadcrumbs is a powerful metaphor, that I personally want to retain even if others have trashed its use in the past. I would send a tug out and bring the ship back into port

@Scott_Sauyet

I think @pmario’s story metaphor is great for smaller chunks, without too many overlapping paths. But it breaks down when there are too many links.

• When faced with a problem, we can find a way to address it.

I did not illustrate it, but as I said;

@TW_Tones

having an independent position stored for each story and a current story and to navigate away from the current story always returns to your original position in the current story unless you change story.

Examples may include;

• Using small text for the non current stories, or hide them behind a more
• using sign posts show links to the other stories not every item in each story
• Introduce other graphical representations, or popup etc…

@Scott_Sauyet

Let’s add opt-in breadcrumb functionality. But here I mean web-standard breadcrumbs, and not a full story/pathway/tracks/trail feature.

I am not sure there is a web-standard, there is a broken use. I feel the best way to overcome this is as follows;

• What ever recall it and create describe is as it works, like defining terms
• Since people may expect a hierarchy, others historical crumbs, others stories, journeys or paths lets look at addressing each of these.

@Scott_Sauyet

It sounds fairly simple to implement, so long as tiddlers live only in one hierarchy. (Just give each tiddler that live in a hierarchy a field that notes its parent, traverse the chain until one doesn’t have a parent, reverse the list and display it as a list of links, in whatever pretty format you like

• I have already successfully done this, initially using the KIN operator, subsequently Recursive filter operators to show all tiddlers beneath a tag and all tags above a tiddler
• Based on the TableOfContent root tag on TiddlyWiki.com

@Alvaro

I have doubts about: how/where we would want to display it. It shows new questions about how it could be implemented.

It can be in or below the tiddlers subtitle if relating to the tiddler, and it can be toggled on/off display.

@Alvaro

Would the use of this navigation be stored in any place? Someone might want to move forward/backward, although it would be too work to implement it.

• If we are representing a tag hierarchy such as the existing content there are ways to derive it rather than store it.
• If we are doing a historical breadcrumbs we can store in a temporary data tiddler, or use the existing history (but It is inadequate)
• If we are using stories/journeys etc… we need to store a list and current position in that list.

@Alvaro

Another idea, and more complex, would be a kind of wizzard/navigator (tiddler) for the documentation with its breadcrumb menus and one or more stories to facilitate the navigation.

• Yes, this is what I think is the best approach, even if we all need to work together to get a more comprehencive solution.

[pmario]

I did rename the thread to

Can Hierarchical Navigation Benefit TW Documentation?

It makes it possible to “spin off” some new threads about more dedicated navigational “flavours” like:

• Breadcrumbs
• Single Stories
• Multi-path Stories
• Tutorials
• … you name it

[pmario]

@Scott_Sauyet

@pmario

If users are new to a topic I think it’s important to provide the hierarchical context a tiddler is in. Once users are familiar with the whole system, this information will be less inportant for the understanding, but it can be a “quality of live” improvement, because it provides a nice and fast way for “linked navigation”

I think there’s some problem with “the hierarchical context a tiddler is in”. When we have a single such context, there seem to be a number of good options. But nothing seems to work well when there are many.

I think we did have some decent tools to visualize “stories” and show the “context”, a tiddler is within that story, with TWclassic from May 2011 in the “Recent tab” eg:

For a Complex UI

1. Story Selector … with 4 possible stories … 2nd one selected
2. The “HowTo Freestyle” story TOC
3. A tabbed Story-river … so only 1 tiddler is shown at the time

• The tabs are dynamically expanded so it’s “kind of a history” … breadcrumb like nav

4. A modded version of Saq Imtiaz’s NavigationMacro (kudos go to Saq
5. Previous Button
6. Next Button

For “production” the right sidebar would be hidden.

IMO today this could easily be replicated with an improved “Tabbed Internal TOC”, a new TW5 NavWidget (4) and a bit of filter “trickery”.

A simplified version to publish a Single Story

… Just brainstorming

have fun!
mario

[TW_Tones]

I like the use of

@pmario , with a mouse over title.

[pmario]

Yea,

@TW_Tones

It has mouse-over titles and can be clicked to navigate. (The wikies had been published at tiddlyspace) … May be I should push them to GH pages, for the nostalgic value.

[Scott_Sauyet]

@pmario

@Scott_Sauyet

I think there’s some problem with “the hierarchical context a tiddler is in”. When we have a single such context, there seem to be a number of good options. But nothing seems to work well when there are many.

I think we did have some decent tools to visualize “stories” and show the “context”, a tiddler is within that story, with TWclassic from May 2011 in the “Recent tab” eg:

I think I’m assuming a different context than you are.

I agree that there are plenty of ways one can design an entire UI to handle multiple trails through the data. I do so in many of my wikis.

But I thought we were talking about enhancements to individual tiddlers, likely with what are traditionally called breadcrumbs. I would expect something such as the MDN example you posted, References > HTML > Elements > <td>, or my suggestion above of something like this:

For tw-com, I was thinking of this for reference documentation (as opposed to other sorts of documentation such as tutorials, how-to-guides, or explanations, as described by the divio documentation system.)

For this style, it shouldn’t matter how we hit, say, Filter Expression; the path we took to get there should be irrelevant, and so would some external “currentStory” definition. It should still show it with Filter Syntax as its parent and Filters as its grandparent.

What you’re describing is interesting, and I’d love to see work towards making that simple to use in TW5. If we can show in any way that the user is on Step 4 of 6 in the current story, especially if we can also easily offer the choice of different stories, then we can offer a great new navigation option.

But for breadcrumbs, I think we should be looking at something simpler.

@TW_Tones

• You could say my first answer to the OT is;

Can Hierarchical Breadcrumbs Benefit TW Documentation?

• Yes they can, but they are insufficient

The idea here, at least as I recall, was as an additional source of information, not to replace any existing tidder metadata. I would phrase the question, “If we had a simple technique to create hierarchical breadcrumbs, could we use it to make tw-com more useful as a documentation tool?” I don’t know if that’s how the OP was intending, but that’s definitely how I’ve been interpreting it.

@TW_Tones

I understand some are focused, not on breadcrumbs, and more on hierarchies, but TiddlyWiki needs to cater also for non-linear, multiple stories and journeys and other representations.

Absolutely; this would only affect a few portions of tw-com. Not everything is hierarchical, and this might have problems for those tiddlers appearing in multiple hierarchies. Still it would be a worthy addition to the current navigation idioms.

@TW_Tones

To me, Breadcrumbs is a powerful metaphor, that I personally want to retain even if others have trashed its use in the past. I would send a tug out and bring the ship back into port

Can you explain how you see that metaphor, and how it might differ from what I think is the common usage these days, to wit, breadcrumbs describe a series of steps to get back from the current location to the starting point, the root? The navigation of full stories, including links to nodes not yet visited, is not part of this, nor, despite the fairy tale heritage, is the exact path you took to get here.

@TW_Tones

@Scott_Sauyet

Let’s add opt-in breadcrumb functionality. But here I mean web-standard breadcrumbs, and not a full story/pathway/tracks/trail feature.

I am not sure there is a web-standard, there is a broken use. I feel the best way to overcome this is as follows;

“Standard” was not the right word, but it is a well-understood technique for hierarchical data. For instance, the MDN page for Breadcrumb Navigation includes this header:

References > CSS > CSS Layout cookbook > Breadcrumb navigation

Practically anyone who’s used the web understands this. It says you’re in “Breadcrumb navigation”, which is in the “CSS Layout cookbook”, which is in the “CSS” section, which is inside “References”. It is only useful if there is a hierarchy, but it’s a simple, unobtrusive, effective way to offer a “You are here” signpost.

[TW_Tones]

As an exercise in producing a hierarchy I am experimenting and brainstorming making the TableOfContents heirachy display on TiddlyWiki.com.

• To avoid definition issues I will call the result a “location bar”
• It is looking quite good so far, I will share back

The key area at issue for me is when there are two paths to the same tiddler;

• Have a look at the “TiddlyWiki Hangouts” tiddler.

It’s not how to retrieve this alternate path, but which is to be default or how do I indicate the alternatives?

[Edited] Parial Implementation demonstrated here location-bars

[Scott_Sauyet]

@TW_Tones

As an exercise in producing a hierarchy I am experimenting and brainstorming making the TableOfContents heirachy display on TiddlyWiki.com .

I look forward to seeing it!

@TW_Tones

The key area at issue for me is when there are two paths to the same tiddler;

• Have a look at the “TiddlyWiki Hangouts” tiddler.

It’s not how to retrieve this alternate path, but which is to be default or how do I indicate the alternatives?

Right. This is what I’ve been discussing as being more difficult. I don’t think it has anything to do with your implementation; it’s a hard problem in general I noted it above with `Drag and Drop Mechanism", pointing out the first two of these:

Features > Drag and Drop > Drag and Drop Mechanism
Features > Importing Tiddlers > Drag and Drop Mechanism
Reference > Mechanisms > Drag and Drop Mechanism

I don’t know if there are any tiddlers on TW-com which have more than three such paths, but it’s easy enough to imagine wikis with tiddlers that do. Perhaps it’s simply best in these cases to show the multiple location bars. Wikis which have too many of these would simply be better off not opting into this navigation tool.

Or the tiddlers themselves could simply have a field which chooses the best parent to display:

title: Drag and Drop Mechanism
tags: [[Drag and Drop]] [[Importing Tidders]] Mechanisms
...
location-parent: Mechanisms
...

and in this case, the only bar to show would be Reference > Mechanisms > Drag and Drop Mechanism.

[TW_Tones]

@Scott_Sauyet

Features > Drag and Drop > Drag and Drop Mechanism
Features > Importing Tiddlers > Drag and Drop Mechanism
Reference > Mechanisms > Drag and Drop Mechanism

See my current handling of this DragAndDropMechanism

@Scott_Sauyet

Or the tiddlers themselves could simply have a field which chooses the best parent to display:

Good idea,

Another way to deal with this would be in two of the places Don’t link to the existing tiddler, create a new one in which you mention the linked one.

• There is value in curating the content to some simple rules to make it more amenable to structure navigation.

[Scott_Sauyet]

@TW_Tones

See my current handling of this DragAndDropMechanism

Interesting! And quite a bit different than what @pmario is proposing. I’m curious what you mean to imply with the icons ⮌ and ▲.

I think this technique would carry us a fair way, but if the number of paths makes this exceed a single line, it would get pretty ugly.

I don’t know if I can find time, but if I do, I will try to do something similar with my idea. It doesn’t sound very hard to implement, but I’ve said that before…

@TW_Tones

Another way to deal with this would be in two of the places Don’t link to the existing tiddler, create a new one in which you mention the linked one.

I’m afraid I’m unable to parse this. Can you expand a bit?

[pmario]

@Scott_Sauyet

Or the tiddlers themselves could simply have a field which chooses the best parent to display:

title: Drag and Drop Mechanism
tags: [[Drag and Drop]] [[Importing Tidders]] Mechanisms
...
location-parent: Mechanisms
...

That’s exactly the reason, why I did create the TocP plugin, which uses the “parent” field to define a unique path for TOC-like implementations.

Since there can be several fields, it’s possible to define unique paths for each usecase. eg: tutorial, explanation, reference …

BUT … maintaining such relations is very time consuming = “costly”. So there needs to be a second mechanism, that is easy and fast to maintain. … That’s the “story” idea, that uses a field, similar ot the “list-field”.

List-like fields are easy and fast to manipulate, but they their downsides too. eg: list-fields can only contain tiddler titles. It’s not possible to add filters to them, which my story plugin allows.

[TW_Tones]

@Scott_Sauyet

Can you expand a bit?

I will try.

If you take the table of contents as an example, additional content tiddlers could be created, instead of tagging one original tiddler with multiple parent tiddlers. The content of the new tiddlers can point to the original tiddler as a cross reference but by avoiding one tiddler being tagged with multiple members from the same tree the data is “normalsed” and there will be no tiddlers having multiple parents. Thus every tiddler has a single path back to the root.

[Scott_Sauyet]

@pmario

That’s exactly the reason, why I did create the TocP plugin , which uses the “parent” field to define a unique path for TOC-like implementations.

Since there can be several fields, it’s possible to define unique paths for each usecase. eg: tutorial, explanation, reference …

BUT … maintaining such relations is very time consuming = “costly”. So there needs to be a second mechanism, that is easy and fast to maintain. … That’s the “story” idea, that uses a field, similar ot the “list-field”.

I think this would not be costly if it were simply a way to privilege one of the possible paths to the root over the others. No tiddler would have to use it, and it would only be useful for those with multiple such paths. All it would do is to make one path the default – or the only – navigation bar.

I’m not sure if I have the skills yet to do what I’m imagining – and I owe my periodic table stuff some real time – but if I can manage it, I will try to demo this idea soon.