Mixed thoughts on how to improve stuff for new users

#1

The following was split out from the thread This should attract more users!

/twMat

Before I start - I want to be emphatically clear:

  • I AM A HUGE FAN - of TiddlyWIki
  • I am only speaking below - from a new user’s point of view
  • I am NOT - and NEVER will be a developer - it’s not my passion
  • I AM passionate about the things I spend my time on - and TiddlyWiki has occupied a lot of my time
  • I do want to and have a desire to help newbies - since I don’t ever plan on being a developer

That said:

  • Simple Things - Like:
    • Examples in the Doc’s
    • Simple - definitions - - - don’t give me the Dollar word - when a Dime word - will suffice
  • Show links to:
    • Tiddlyhost - where you can create/test/share <— this is a hidden site - on search engines
    • ,…

I’ve been scouring Google looking for examples - and I just found this!

I had no idea this existed - even after creating my tiddlyhost site - - wow!

I agree - for us N00bs - that are not developers - we don’t really care about all the “coding” stuff (or it could be just me) - but I just need something that fit’s my need at the moment - and am willing to put in the elbow grease - assuming it will pay off in time saved.

And yet again - I find something new,… - no idea this existed - google search does not return it - for my searches,…

  • Thanks @twMat - yet another link to add to my growing list of “hidden” - non-findable (at least for my searches on Google) TiddlyWiki Gems,…

I think this is the default mode - for TiddlyWiki - and as someone that will always be new (aka - i will never be a developer - i’ve no desire to be one) - it can be a tough uphill battle - when looking for that “magical” keyword/plugin/etc. combination,… - This is real life afterall.

Example pages are nice - but I would rather just have “working examples” in the doc’s.

  • Since (for example) my colleague - a python programmer - complains about the lack of working examples
  • He wanted to list a group of tiddlers - and put it “List Tiddlers” in the main tiddlywiki site - only to have nothing he can copy/paste
  • I too have mentioned the lack of actual code to be able to coy/paste - and just see it work
    • Here is what comes up when typing 'list tiddlers" (my colleague showed me this today) in the search box: (and yes - before @TW_Tones says I am searching wrong/inadequate/incorrect/etc. - - I am just showing what the “regular joe” would search for - ,…)

image
image590×730 54.8 KB

  • He then clicked on Tiddlers - and there was nothing he could use - - - he states that he does not know what to search for - for listing his tiddlers,…
    image
    image2188×720 105 KB
  • I got to this point - or the realization set in - when I started using a modified version of Projectify - that eventually led me to the tiddlywiki site (I had no idea it existed)

For me (when I was newer) - the main issue - is not the plugins - or how I had no idea that it was a drag and drop, save and reload - - -

  • Rather - I had no way of “figuring out” how to do simple things
    • List your recent files
    • List files with specific names
    • Create a button to create a new tiddler - or update a field
    • I (just recently) started using Tags and Fields - - I never understood the power they had - or even why anyone would want to use them
      • I really thought Fields were useless and Tags too,… (yes - I was wrong)
  • Or
    • How to actually use “tags” - - I did not use them - unless someone said to add them - - they did not make sense (still don’t - at various times)
    • How to use the Train station - I still don’t get it - is it like a UNIX pipe? How do the Boxcars work? Are they containers - like Docker?
      • The train-station with it’s tracks are shown in the main page - but there is nothing I can copy/paste - to see “what” or “how” to use it
  • Or
    • A simple link to “talk.tiddywiki.com” - - - I joined a while back - forgot about it - and struggled and happen to stumble back here - ,… - a link would have saved me soooo much time ---- I can’t be alone in this,…
    • A place for newbies to post questions - just for newbies - in the language of newbies <— this would be MOST welcomed - -
    • Where newbies can help other newbies - get the right verbiage - to avoid wasting folks time
    • maybe newbies.tiddlywiki.com or something ot the other - where it’s linked on the main tiddlywiki site,…
  • This would be great - and yeah - so much easier than the “grock” tiddly site - - that I tried (in vain) to go through may times - but got lost - so I gave up

Sort of brings me to the point - - - “grock tiddlywiki” <— I would have never figured out to do a Google Search with this phrase - – why can’t it be more like “TiddlyWiki How To create a table with examples” or “How to use Tiddlywiki to create a tiddler with an address book” or ,…

I am not slamming - apologies if it sounds that way - I am passionate about where I spend my time - and tiddlywiki is worth it.

TwN00b

2 Likes
This should attract more users!
#2

There’s a lot to unpack here. I’ve been concerned about the documentation since I got seriously involved in the community two years back. But I’m having a hard time figuring out useful proposals for improvement. You have a list of “newbie” questions, but it’s likely a very different list from those of other newbies. So if we have a large list of such Q & A’s, how do we organize it?

I feel as though there are many examples already included; more would always be helpful, though.

Any specific examples?

And as to findability of the links site or the forum, how would you want to make that more prominent than being in the first menu on the top of the TW page? This is not a rhetorical question; really, how would you think these can be made easier to find? And as for TiddlyHost, there are three tiddlers open when you load the main page – and they’re also visible in the default tab in the sidebar menu: HelloThere, GettingStarted, and Community. The second one starts by discussing TiddlyHost.

Now that you have at least some sense of how these work, would you be willing to write some documentation on them targeted at new users? It doesn’t have to be perfect; I’m sure some more experienced users would be more than willing to polish it up.

Do you think that this forum is not appropriate for that? I think there are numerous users here more than willing to respond to newbie questions; many seem to enjoy not only helping out but also teaching as they do so.

Overall, you have lots of great points, but I’m wondering if you have more concrete suggestions for fixes?

#3

Hi @Scott_Sauyet ,

Thanks for taking the time - and yes - I would welcome helping in any way.

  • Please note - I might not get the verbiage correct - but will try
  • Also, feel free to correct anything/everything - as I understand most of this is still in flux

Types of “general” newbies:

  • I am not sure if I am any different from the newbie’s - as most folks - when learning something tend to have basic questions
    • Mainly - can I get workable examples on A, B, C,…
  1. There are folks (like me) that are consumers - and have (in all honesty) no desire to become developers - none, nada, zip, zilch
    • I own so many software applications - that I’ve used throughout the years - that just don’t do what I can do with TiddlyWiki
    • I am willing to pay for ‘good’ software - so long as I can benefit from it - but I will always look for the open-source alternatives - since those (IMHO) tend to get made better - faster - ,…
    • Obsidian, OneNote, GoodNotes, OpusDomini, etc. all had their use - that I was able to replace with TiddkyWiki ← It’s True!
  2. There are consumers that “might” become developers - and they will be more into the nut’s and bolts of TiddlyWiki
    • They will learn and run with TiddlyWiki - including participating and pushing feedback +,…
  3. There are developer-types - that love to tinker - and they will most likely use TiddlyWiki differently
    • Insert Technical Jargon here
  4. There are hard-core Dev’s serious about extending and creating App’s using TiddlyWiki - they also think different from me
    • At this point - I nod off to sleep
  • There are others - but the above groups (IMHO) are the main ones

Organizing:

  • Also, for organizing - this is a complex subject - as we don’t know the who will visiting - or what the skill level will be

    • Simple examples - how to “do” something - with examples - simple
    • Take a simple example - and expand it - more complex -
    • Take a complex example - and use magic to showcase the power of TiddlyWiki (FYI: I won’t be reading this part of the examples)

  • We can have various sections - some examples:

    • Casual Users - just interested in the application usage - how to create a tiddler -
      • Create an Address Book, Todo List, Manage a Project, Calendar Entries
      • Create a cookbook, a Journal notes area, etc.
      • Think of the Franklin Day Planner – people understand that concept - and no - I am not referring to Getting Things Done ← yuck
    • Users interested in just a little more - than a casual user
      • Creating a basic TiddlyWiki Application - nothing to fancy - but has “stuff” - from above
    • Developer Types -
      • Creating a TiddlyWiki Application
        • Like your Bible - that’s awesome! ← I just have no idea how it works - I don’t understand the code
        • Projectify - a decent replacement for the Franklin Day Planner System
        • Plugins, (insert technical stuff here - things I don’t know)
    • Developers - Advanced
      • Insert Magic Gobbledygook and technical jargon here

Yes, more examples - always more examples - Please - and we can make them: (more is always better - we learn by doing)

  • Complete - so that we can copy and paste them into a tiddler - and they “just work”
  • A subsequent section - making them more complex - based on the type and interest of the user

Sure:

  • What is a: https://tiddlywiki.com/static/Railroad%20Plugin.html ?
    • I see the page - but it’s technical - yet - it’s referenced in a lot of docs
    • The verbiage is a bit much (for me) - as well as the examples -
      image
      image1032×940 38.2 KB
    • I understand that this is supposed to add a suffix of “y” to “x” - - - but “how”?
    • The examples don’t really show how to do this
    • And nope - nothing I could use,… - sorry - true - so I went to Google,… and Reddit
  • I have other questions I posted - but I think the above should help
  • This one is a bit harder
    • The first Tiddler is busy, noisy and uses to much color - - to be honest - it “shouts” at me - - It can be just me - but I get information overload when i go to the main site
    • The first thing I do is “close” all the Tiddlers - - and breathe a sigh of relief - noise gone
  • To be honest - I did not know that “talk.tiddkywiki.com” was listed three times - since I quickly close the tiddlers
    • To be fair - any site that yells at me - I will avoid - and only go to “if” I “REALLY” need to go there,… - it might just be me though
    • IT’S SORT OF LIKE: TYPING IN ALL-CAPS <— sorry - just trying to make a point
  • To make this better - Can we “ease” folks into the site?
    • Maybe something that is “softer” - less packed?
    • it’s OK if it’s a long main page - where we need to scroll downwards
    • Also, it’s better if we split the single multi-combined page to different pages
  • A page for newbies - like:
    • “New Users: New To TiddlyWiki?” - something that allows new users to open a page to another “site” or section or - whatever
    • This allows folks to see the “Good” in TiddlyWiki - with jump pages to tiddlers, examples, how-to’s and links to the Support groups, Example Sites, etc.
  • Examples:
    • Can we add in the “talk.tiddlywiki.com” posts - inside the “search” bar on the main TiddlyWiki site?
    • This would help with searches - (I hope)

Yes - sign-me up. Just tell me where to put the examples - and I can use the examples I use - and why I needed to use them.

Well - the site works - and yeah - I can ask - but at times - when I read some of the responses,… (If I am allowed some honesty)

I get that new folks don’t know “where” to post - or “what” section to post under - or “how” to post - or even “why” we should NOT post - ,…

Due to the complex nature of TiddlyWiki and the advanced levels - of the users - on this forum - I’ve not posted 32 items - - - yes - I save my questions - in case I need to refer to them in the future - and for those - I’ve gone to Google/Reddit/etc. to get the answers - and not here.

I now spend at least 1/2 a day doing web searches - to see if I can get an answer - before I even consider posting here - and when I do - I do try to use the correct words. However, I am not a developer - but folks seem to think I am “writing an application” - - I am not - I am just creating my own personal bible study - using dictionaries.

I would rather work on building folks up - and helping tech progress - since the world is complicated enough.

Let me know if you need more examples - I can provide them - and yeah - I am happy to help.

Thanks for your reply,

TwN00b

#4

If you write clearly, others can update to match the jargon, and perhaps learn where the jargon itself is too obscure.

That’s the idea. The documentation should be collectively developed. I might start something, only to have Springer correct my misunderstanding, and then you could further improve the readability, and later, when there is a new version with a minor change, perhaps Mario will update to explain the changes.

But everyone’s idea of a basic question is quite different. One person’s first question is how to add italics, another’s is how to customize a list of links, a third is how to make a plugin to communicate with an external site.

Perhaps; it really depends on A, B, and C,… and perhaps on X and Y as well.

It also depends on what you mean by “workable examples”. Most examples beyond simple formatting will depend on filters and lists… which in turn depend on the data in your wiki. So an example like this

Using a TagWidget Inside a ListWidget.json (605 Bytes)

A slightly more performant option is to use the `variable="transclusion"` attribute in the list widget.
In this case, the variable `<<transclusion>>` has to be used inside the list widget instead of the 
`<<currentTiddler>>` .

<$macrocall $name=".example" n="1" eg="""<$list filter="[tag[HelloThere]]" variable="transclusion">

* <$link to=<<transclusion>>/> is tagged with: <$list filter="[<transclusion>tags[]]"> <<tag>> </$list>

</$list>"""/>

will work great if you download it and drag the file to tiddlywiki.com. But it uses the .example macro, which is part of that page, but not of the default edition. And even if you grabbed that too. for this to be a useful demo, your page will have to have tiddlers with the tag HelloThere. If you don’t, you won’t see anything.

Depending upon what you mean by that, you may find that many of TW features are simply out of reach. If for instance you are uninterested in learning about filters and lists, then you reduce TW mostly to a way to format and organize your text. If you ignore transclusions, then some of the key reuse that makes TW so powerful is lost.

If however, you simply mean that you’ll learn whatever Wikitext you need, but will steer far clear of even touching JavaScript, then you’re in very good company. Many of the advanced users here work that way.

What I meant by different newbies having different questions was that your post included this:

This list is very specific to you and to your usage. Another newbie might not think in terms of “files”. (While we understand what you mean, it’s not how we discuss tiddlers here.) She might have no idea why you want to create a button to create a new tiddler, as it already exists and is visible in all the common editions. She might intuitively understand the need for tags and fields. But she might still be stymied by other things which come to you naturally.

That’s why we need to organize the information we present, but there is no obvious way to determine the best organization.

How to create a tiddler should certainly be part of the basics. But all these others are going to be much more sophisticated. As I said, my work on a Recipe Edition has fallen down, but assuming that I can do that soon(ish), and assuming that we can create other similar editions, perhaps we can give new users the ability to use TW for various specific purposes. But these would be useful samples; hopefully the curious could then learn how to modify TW for their own purposes, but they wouldn’t serve as tutorial-level documentation.

Can I suggest that at first you just do it in a standalone wiki available to the public (Tiddlyhost, GitHub, wherever), and then send us a link to whatever tiddlers you would like to see incorporated in the documentation. Once you have something to contribute, there are tools to let you contribute suggestions directly to the documentation.

First off, that tiddler really should make the initial “railroad diagrams” a link to the Wikipedia page or some other good source of that information.

I agree that this tiddler is hard to understand. A big part of the reason is that it is so meta. It uses Railroad diagrams to describe the syntax for creating Railroad Diagrams! It would be nice to use different color schemes for the two levels of diagrams used.

But first of all, this is a fairly specialized tool. It is used for describing grammars, almost always for programming constructs. You can see how it looks in Filter Syntax and then by clicking on the diagram terms such as Filter Expression, drilling down through the levels of the filter syntax. A good example is Filter Step:

image

This should look something like railroad diagrams, which show what tracks a train can run on across the yard. A train can’t make a hard turn, so only certain options are allowed from any position. In this diagram, we can either start with a ! character or skip it. Those two options come back together, and from there we can either omit the operator/suffixes bit (by, according to the note, defaulting to “title”), or go through the operator/suffixes bit, and again we come back together, to require a parameter, and either continue on or add a comma and another parameter. The operator/suffixes section allows us to either include or skip an operator, then include any number of suffixes (including none at all), each preceded by a :.

This captures all grammatical filter steps. This does not mean the string in question makes logical sense, but it is at least syntactically correct.

The filter step compare:number:lt[3] would proceed like this:

  • We start at the left end of the track
  • We skip the !, riding on the top branch
  • We have an operator of compare, on the main track
  • We have the token : followed by the suffix of number on the main track
  • We follow the lower track back to the main branch
  • We have the token : followed by the suffix of eq on the main track
  • We have the parameter of [3] on the main track
  • We finish on the right end of the track

But again, this is a fairly specialized tool. It is excellent at making the Filter syntax more clear, but unless your wiki is describing grammatical constructs, you’re not likely to ever need it.

Tiddlywiki seriously blurs the distinction between writing content and creating an application. One of the main points of wikitext/filters/widgets is to make it so you don’t need advanced programming language features to write more dynamic views of your content.

Edit: this is very much worth reading: Improving TiddlyWiki Documentation, as is 7 Steps to Improve the TiddlyWiki Documentation .

2 Likes
#5

I did create a PR at GitHub to change that. It now links to the plugin syntax description, instead of transcluding it.

It looks like this now:

image
image1537×813 44 KB

#6

This could probably be achieved by adding the Tour button to the HelloThere tiddler with a brief explanation of what it’s for

1 Like
#7

That is definitely an improvement for plain readability.

But I was thinking about the syntax description itself. I would love for the diagrams showing the syntax of the railroad diagrams themselves to look different from the sample syntax diagrams. Something like this, perhaps:

image
image776×1304 48.4 KB

It would be great it if the syntax diagram plugin itself could accept a class parameter, but without that, we could do a docs-only fix by wrapping another <div> around those with a dedicated class and adding a little CSS. This is probably not exactly the right way to do it, but it should show the idea:

$__plugins_tiddlywiki_railroad_syntax.json (6.0 KB) (download and drag to main site.)

The colors are pretty random; someone with a better eye might give a better idea.

#8

I think this attitude is a big mistake. Your image of “developer” is something in your head and possibly characterised by what you don’t know, not what you do know.

  • Sure you can ask for and get “no code solutions” from tiddlywiki and get support to achieve this.
  • minds are not developer non-developer, they are all just minds, one has the experience, the other does not.
  • TiddlyWiki plays a role in democratising software for us all and good way to enter the world of software development. You see, coding is effectively saving algorithms into a computer, you will only ever be empowered to do this if you don’t set up barriers to your own learning.
2 Likes
#9

@TW_Tones I really like your answer.

Exactly! I see myself as the eternal newbie in a way (User for 15-16 years LOL). Lots of stuff I cannot do (today) but somehow find a way to my new useful Tiddlywiki. It will grow an get better constantly as I learn new tricks.
When I started using Tiddlywiki, I would never have thought that I could create my own craft wiki with everything I need. Household and much more - Never thought that would be possible for me.
In some ways I think of Empty as a carefully created box for collecting building stones - Kind of Lego for grownups.
The combination of Tiddlywiki and the community makes it possible. The best thing I know is when people share a link to their wiki. Always something to admire and learn from. How did they do this or that. Oh…this way. (he he I could use the same solution twisted a little to my own wiki.)

Thank you to everyone for this!
Tiddlywiki is keeping the little grey cells alive in this old lady.

6 Likes
#10

Exactly the same feelings :slightly_smiling_face:

1 Like
#11

i think the difficulty here is that the main site is trying to do many things:

  • advertisement / elevator pitch / first impression
  • demo of the platform and its capabilities for prospective users
  • beginner tutorial for setting up and using a first wiki
  • full documentation on all the minutiae and nuts and bolts

we’ve discussed this problem but i think it really shouldn’t be trying to be all these things at once. or at least, have toggles to switch between these modes so users aren’t bombarded with all of them at once.

a page separate from the full docs with a sleek demo and “first impression” page / site that transitions into a beginner tutorial would go such a long way, i think.

currently i think the best we have is https://tiddlywiki.com/editions/introduction/#TiddlyWiki:TiddlyWiki but it doesn’t have anything on saving or setting up your wiki as a first-time user.

2 Likes
#12

Incidentally this thread The $testcase widget and CompoundTiddlers raised some related issues.