TiddlyWiki documentation, structure, and audience

Community Projects Documentation
#1

This is in response to Getting Tiddler field isn't working - #6 by twMat

Pretend you’re brand-new to TiddlyWiki and not the TWizard that you are now. Perhaps all you know is general wiki stuff, like from Wikipedia where you learned about CamelCase and some basic markdown.

If you’re searching for something like, get date from other tiddler, the search results are, frankly, discouraging. I excel at modifying search criteria to try to find a solution, but between Talk and the TW site, I was not having much luck. I eventually found that format operator page and there is no clue at all that I need to be incorporating this operator inside any other syntax structure. That information is simply not present in any way, shape, or form.

Worse yet, we’re talking about a wiki, the end-all and be-all of hyperlinking and cross-referencing information between various and disparate articles of information. But, there were no hyperlinks that might clue me in on the outer syntactical usages.

I learned years ago the value of “know your audience.” The audience for much of the TW site seems to be the intermediate to advanced user. It’s a big stumbling block for a reasonably technical user like me. By now, I could be doing so much more with TW than I am now.

Having said all that, I must share a mea culpa. I know of Grok TiddlyWiki, but I have been remiss in reading it. I keep thinking I can find the answer on TiddlyWiki.com and keep forgetting to use that third-party site.

2 Likes
#2

A “TiddlyWiki in 24 Hours” book would be sweet.

That said, I find the Contents tab, though, is pretty good. Everything is in there. Maybe some of it too technical, but loads of folk here can make anything a little bit more human friendly (or simply fill-in any blanks) based on questions you have that refer back to anything in that documentation.

Screenshot 2022-03-15 8.02.46 PM
Screenshot 2022-03-15 8.02.46 PM325×550 23.4 KB

#3

@DesertDwarf - your frustration is justified. What, in your opinion, would be a good way to present the needed guidance for this matter? In the end, it is Jeremy who decides what goes into TW as well as into tiddlywiki.com but the more concrete your suggestion is, the easier it is to envision it and discuss around it, and to form an actual “pull request”.

#4

You’re going to have to fill me in sometime on the ratio of “deer in the headlights” vs “pull requests? Yes!” reactions that gets.

Pull request. That’s what I call it when I present my extended index finger to somebody…

The thing you’re referring to, that feels way too much like techno-babble.

#5

Could tiddlywiki.com possibly capture search requests (or, when a search comes up empty, offer a form to confirm it’s a real human and register a quick automatic note to the effect that “xxx” was a search term of interest)?

I realize this is at odds with its “this site is nothing more than an instance of TW” mission… But at least, some big data would emerge about what terms deserve an alias or redirect.

My own pet peeve is that “boolean” isn’t in there (apart from one oblique reference), nor can we find “disjunction”, “nand” or “xor”. Any logic-minded person trying to look for how to filter for ((This OR that) but NOT (the other)) doesn’t find a simple overview. As with the nth operator, once you know what words to look for, you’ll find the info. But novice searchers can have the experience of bush-whacking for quite a while.

-Springer

#6

LOL! Brilliant! Sorry, I should have known better: When you post a code contribution on github and request that it is included into the software code, this is called a “pull request” or a PR.

#7

Or “Tiddlywiki for dummies” :stuck_out_tongue:

It is real problem, the documentation is too technical. For example, the tiddlers Learning and Working with TiddlyWiki are long lists. Maybe if they will be structured depending on audiencia (newcommers, basic users, intermediate, …) with some hints could be great.

P.S.: Yes, I could do something, but I already have a list of “projects/features” for tiddlywiki, and with one more it would be a interminable TODO list.

#8

TiddlyWiki search at the moment is configured to return results with an “exact match” for “every” word in the search input.

So the more words it contains the less results it will find, because all words from the search string need to be matched. TW doesn’t contain any AI algorithms, that try to make sense of our search terms … yet :wink:

So the “search term” date would have probably returned better results. Where Date Fields probably would have pointed you into the right direction.

grafik

1 Like
#9

This might be slightly off topic, but one thing that I would love is a separate site where coders take complicated snippets of code from threads here and “translate” them into English. This is a short example, but there are really long ones too, with things like vars and let and set and get and others-that-I-forget.

<$text text={{{ [<currentTiddler>addprefix[$:/myprefix/]] }}} />

  1. Grab the title of the current tiddler.
  2. Add the string of characters $:/myprefix/ as a prefix to the preceding.
  3. Display the result as text but not as wikitext.

In this case I was able to figure it out myself, but there are many many examples that boggle my mind.

To be honest, if I had 20 or 30 distinct translations like this of long snippets I don’t understand, I probably wouldn’t need to use the documentation much.

#10

So no one’s written an improved search engine? so you could say

@Learning +text:date -movie

And you get all those items tagged Learning containing “date” in the text field but not the term “movie” ?

#11

Cool idea. A complimentary alternative would be to take out snips from TW core or distro and explain them. That would certainly be a valuable and interesting, but ambitious, documentation project: Make a meta tiddler for each tiddler in the core, to explain it.

A “reverse” idea might for doc tids to link to real tids in the core that use the described tidbit, for close inspection.

#12

Those might be interesting projects, but I see translating snippets like learning to drive the car, and translating shadow tiddlers as learning engine mechanics. Most of us just want to learn to drive.

#13

This would be explain again the concepts of how tiddlywiki works: wikitext, transclusions, filters, macros and widgets. And then the coders have to explain how these parts (of tiddlywiki) work together in each snippet. IMHO, it is a bit repetitive. Maybe it is better work in explain better the main concepts and then we show how they can be used together.

1 Like
#14

Going back to the OP, @DesertDwarf makes some good points, all of which, to me, allude to the “curse of knowledge” possessed by the authors (me included). That’s an issue that befuddles many authors of technical prose. See, Pinker.

I don’t know what the solution is. The information as it stands needs to be there, but that’s not to say there couldn’t be a higher level introduction to the basic ideas as @Alvaro et al suggest. But what does it say about TiddlyWiki if, for the non-technical person, they need to read a book first (assuming a book is even needed)?

I think we’d all agree “more examples” are always welcome, but I’d also agree they don’t address the OP as written. :confused:

#15

Ditto, but I do have a thought.

“Tiddler Topic Threads”?

When looking at a specific documentation tiddler, it would be nice to see what the tiddler relates to as per various threads of learning, what might be some good next tiddlers to visit per each thread of learning, what other tiddlers fit in the context of each thread of learning.

Something like that. Not just the tiddlers intertwingled to the hilt, but threads of learning intertwingled to the hilt.

Easier imagined than implemented …

1 Like
#16

Thanks for the fairly constructive discussion.

I am more comfortable now with searching TiddlyWiki.com.

My answer to that is in the first post:

I think if someone was taking on the (fun and exciting) task of learning about TiddlyWiki in the first place, if linking and cross-referencing were more liberally applied, it would make following the bread-crumbs of knowledge easier.

It occurs to me that a mind-map plugin applied to the TW site might show the orphaned items that are examples or explanations of a broader topic. If we can just draw the lines between the individual tiddlers (lol…thanks, autocorrect for suggesting tiddler should be spelled toddler!), it would make the discovery process easier.

Here’s an example I came across a couple of days ago, but it didn’t bother me because I’d already tackled the parent topic:

https://tiddlywiki.com/#Example%20Table%20of%20Contents%3A%20Selectively%20Expandable

If I open that tiddler, there’s not a link back to either #Contents or #Adding a table of contents to the sidebar. So, while I can ultimately get to the Selectively Expandable Example, if I started with that tiddler via a search, I can’t click my way to a parent.

My apologies to those that prefer CAPS for emphasis rather than italics. I emphasize by leaning into what I’m saying rather than STANDING UP LOUDLY! (Also, I’m short, so standing up (but I am standing) jokes would apply. :grinning:)

#17

Not really, I am just talking about brief ‘translations’ of snippets. The advantage would be seeing more examples in use cases as opposed to abstract explanations.

#18

Well, I did warn in my first post that it was slightly off topic…

#19

They would not be just abstract explanations. There would be examples, after the explanations, and hints (basic examples) about how it could work it together other elements of WikiText and filters.