Can Hierarchical Navigation 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 mentioned above.


IMO this could be browser history, which can be activated in the TW ControlPanel → Settings tab.

  1. If the Navigation Address Bar is activated as shown in the screenshot … and
  2. Update history is activated …

The browser history 3) could make sense. … but it does not, since the info stored there is not good enough atm.

  1. The browser back and forward buttons work … That’s a good thing. … But IMO most users don’t know about those settings.

IMO these features especially 2) should be improved and more prominently document.

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”.

  • The initial story could be the summary itself, which links eg. 3 more links to give us an overview
  • A more detailed story could provide a view about the full picture" with all the details

Those 2 “stories” could be created by the author. … Creating stories “in between” those 2 extremes should be easy to create by the user.

IMO that would be a valuable goal.

… just some more thoughts

1 Like

That’s a challenge, which imo would be worth while to experiment with. I do not have a solution, but I’m very interested in presenting information in a context. … Even if the system itself is “non linear” … Or especially if the system is non linear.

I have given this some thought and recall having found a solution. I hope the recollection is correct. I will look for my notes. One memory I have is having an independant 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.

  • think of the words temporary diversion
  • using real world analogues helps

There are other gaps in the documentation and its searchability as well. I recently developed a keywords solution that enhances searchability by promoting some results ahead of others, search tiddlywiki.com for common terms like " filters" and the expierence is poor and even more so if you want a system tiddler like control panel or tag manager.

  • the only thing I need to solve is adding keywords without touching shadow tiddlers, although this would be uncommon except for technical self documentation.
  • although my masquerade solution may be a good solution.
  • the keywords could promote master tiddlers that expose a story or heirachy you could use to take a curated journey.

I think that’s a bit OT here.

I did post some ideas about “searchability” and “rated results” this topic: Can we make standard search a little smarter? - #12 by pmario

1 Like

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 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.

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

But that’s just displaying HISTORY, like the browser back-button!

I don’t believe it is to TiddlyWiki’s benefit (philosophically or otherwise) to rest on facilities provided by user agents. TiddlyWiki should (and does) “stand alone” and do its own thing.

Yes, but that would lead to a huge line of links that simply wouldn’t scale!

That’s an implementation detail easily solved when the design is being thrashed out.

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 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.

@pmario Feel free to move this if you feel it necessary.

Wikipedia says:

A breadcrumb or breadcrumb trail is a graphical control element used as a navigational aid in user interfaces and on web pages. It allows users to keep track and maintain awareness of their locations within programs, documents, or websites. The term is a reference to the trail of bread crumbs left by Hansel and Gretel in the German fairy tale of the same name.[1]

All your quotes miss references. So I think they are your interpretation, with which I disagree. …

Hansel and Gretel’s breadcrumbs lead from their home into the forest. … It’s the path they took to go there, that’s a fact.

The same thing is true for the eg: “Filter Step” tiddler. … If we go back the way as it is shown, we will end up at the home of the “Filter Syntax”, which is the “Filter”.


For new users the filter syntax is very complex and hard to understand. The existing documentation does nothing to help users to immediately see the context the different doc tiddlers are related to.

  • These plugins try to help them with a visual context.
  • The dynamically created structure may not be the only way to get the big picture. You are right, it is a curated one and I’m sure it is a good one.

Is there an existing 3rd party plugin, that is also called breadcrumbs? … I do not know one. links.tiddlywiki.org does not show one.

We can name the plugins .trail … But I would like to hear others first.

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

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

Yes and no

My point being where does a story start?

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

highly relate to my post here in this thread

1 Like

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.

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.

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.

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!

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.

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.

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.

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.

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

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.

Absolutely.

Yes, or stories, pathways, etc.

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

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.

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.

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.

  • 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
  • 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 :nerd_face:
  • When faced with a problem, we can find a way to address it.

I did not illustrate it, but as I said;

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…

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.

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

  • 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.
  • Yes, this is what I think is the best approach, even if we all need to work together to get a more comprehencive solution.

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

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” :wink: 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
  1. A modded version of Saq Imtiaz’s NavigationMacro (kudos go to Saq :wink:
  2. Previous Button
  3. 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 :wink:

have fun!
mario

I like the use of
Snag_2dcd161
@pmario , with a mouse over title.

Yea,

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.