Grok TiddlyWiki update: Seeking feedback, assistance, and funding

,
#1

Hi everyone,

I said in passing a couple months ago on these fine forums that I was hoping to finish a new edition of Grok TiddlyWiki “this summer.” With the end of summer upon us, that might have been a little optimistic, but I’m now gearing up to get everything together in the near future.

Here’s a summary of what the path forward looks like and how you all might be able to help me get this done!

Goals

My goals for the 2.0 edition are, in brief:

  • Update a bunch of minor things which have slid out of date (e.g., GTW still recommends the Google Group as the place to go for TW help, and it still says CamelCase links are the default).
  • Address all the email feedback from users I’ve received over the last months. Most of this is already done, but the changes are unpublished.
  • Refactor the code of the GTW wiki to remove as much legacy stuff as practical, so people will learn good new habits if they poke around. Most of this is already done.
  • Move the suggested startup platform from TiddlyDesktop to TiddlyHost, since that has emerged as a fairly clear recommendation for most new users (thanks @simon!). This will also make it much easier for people who are just getting started to clone their own copies of GTW, since I can host a copy as a template on TH and provide a direct link where you just have to name your copy, select an access level, and click the button.
  • Add new sections covering the most valuable new 5.3(ish) features:
    • Backtick substitution
    • Procedures
      • The curriculum will be procedures-first, and will cover macros later as an additional feature you might occasionally find useful, as well as something that’s good to understand for working with legacy stuff.
    • Conditional shortcut syntax
    • Parameterized transclusions, $slot and fill
    • Functions
    • Custom widgets
    • Cascades

Soliciting outline feedback

If you think I am missing something really important in the list of goals above, or there’s something you find baffling in the new version of TW that you’d like to see more coverage of, let me know! You can have a peek at my somewhat more detailed outline (very subject to change).

Soliciting other assistance

I’m looking for people who would be interested in:

  • Designing a new favicon: I drew the current one myself in like 10 minutes, and it has a funny snub-nose. It’d be nice to get a cleaner one in place! I’d give you a lot of design latitude; it would be hard to do worse than the current version. A banner and/or logo might also be nice, but I’m not sure on that yet.
    • I’d be able to pay some token amount (maybe $50–$100), and would acknowledge you in the book.
  • Reviewing the book: To do a good job with a textbook, I need people to try learning from the sections and let me know what they understood and what didn’t work so well. Either the whole book, if you’re new to this, or most importantly specifically the sections that are new or have gotten major changes. I have a self-imposed soft deadline of 2 months here and still need to do a lot of writing, so if you’d be able to turn it around in a week or so (reading/exercises/comprehension questions on 8 sections or so), that would be fantastic. Your ability to respond to follow-up questions is also important; I find a large proportion of important feedback comes in this follow-up session rather than the initial feedback.
    • I will acknowledge you in the book as a reviewer and assist you with any questions that come up as a result of your feedback. Last time everyone refused other compensation, but I’d also be happy to offer a small gift card to Amazon US if that would be useful to you.

Design work could start anytime. Review phase will ideally start 3–6 weeks from now, depending on how long it takes me to hack out the new sections, and wrap up shortly after.

If you’re able to help with something here, please post below or email me at contact@sorenbjornstad.com!

Soliciting monetary pledges

As with the previous GTW, Grok TiddlyWiki 2.0 will be BY-NC-SA 4.0-licensed and available to read for free. And as before, I would much appreciate donations.

I want to be totally honest here – it’s my intention to complete these changes regardless of funding, and I am not in dire need of money. Please do not direct money at me that you cannot afford to spend. That said, I’m quite busy right now and this is a substantial amount of work, so informal advance pledges would definitely help light a fire under my you-know-where to get it done! If you feel so moved, please post below or email me at contact@sorenbjornstad.com saying how much you’d like to donate, and I’ll follow up with you after publication. You’d be able to pay by credit card through my donation system upon completion, or if that doesn’t work for you, I can arrange a PayPal or Venmo transaction.

Cheers,
Soren

14 Likes
#2

Thanks so much for your contribution here @sobjornstad it is a most valuable resource as testified time and again by new users.

I would consider being carful here, perhaps de-emphasis rather than remove, as there are a lot of solutions, and contributors who will still use deprecated features.

  • Done appropriately users of your document may search for older terms and it would help if they are found and direct them towards the new methods, whilst keeping the old methods out of the learning path.

I will try and assist as best as I can, but as a result of being an “TiddlyWiki old timer” I do find it hard to behave like a naive reader.

As a result I will make a one off donation to support you, but may volunteer more later. I encourage others also to do so as well.

Personally I think Functions are a potential game changer as they are evaluated without the need for wikification, and produce plain text results that can save the conversion to text, and work within conditionals/filters.

  • Perhaps I can find/start a topic that will help inform your work on one or more of your updated content areas, such as functions?

Thanks again @sobjornstad

#3

I’m literally in the middle of using your book. Last night I completed Chapter 4 Section 5 – “Templates and the Current Tiddler.” I’m following all the exercises, implementing the examples, and utilizing the flash-card takeaway system.

I’d be happy to write a review of the wiki-book once I finish working through the current version. What is the purpose and intended audience for the review?

I’ve reviewed books and independent games/software in the past. I’m currently a graduate student. I consider reviewing things to be my most natural skill.

I appreciate traditional long-form programming guides. I’ve previously learned other software systems by implementing examples from guidebooks.

3 Likes
#4

Something like this, perhaps:

Procedures, Functions, and Macros

Procedures are tools for [ … ]
[ … ]
Functions can be used to [ … ]
[ …]
Macros are an older tool, meant to do something similar to Procedures, with these differences:

  1. they [ … ]
  2. and they also [ … ]

Mostly we would suggest that you stick to Procedures and Functions, but if you need to write a Macro or understand someone else’s, then here’s how they work: [ … ]

Donated. I owe you a great deal for the first edition of this book. I’m excited to see the next one!

3 Likes
#5

Sorry, by “review” I mean you would look through the text of the book and give me feedback before I publish it to a wider audience. I’ll edit the original post to be more clear!

If you can find other places to talk about the book though, I’d certainly appreciate it – I want to try to do a little more publicity this time around.

2 Likes
#6

Sorry, this must have come out much less clear than it was in my head. I am referring to the internal code of the book’s TiddlyWiki – not the material being discussed in the text of the book itself. I still intend to cover macros and the most important other legacy features in the text (and if you look at my detailed outline, you’ll find this mentioned there), just use them as little as practical when building the book’s wiki.

#7

I have thought about “reviewing the book” in this way, but:

  • I have a specific learning style that might not be generically better.
  • I have a tendency to go all the way in critiques so the suggestions would be too massive
  • Although I’m considering it, I’m not confident enough in my commitment level right now.

I have also considered engaging with an independent attempt at an alternate lesson plan of the same scale, but that is probably more than I will realistically tackle given other interests.

If I do catch that bug, I’m thinking the best approach for me would be a fully “selfish” lesson plan that isn’t supposed to have mass appeal. I can also attempt a series of rationales for my alternate methods to Grok that might effectively constitute feedback.

If I seriously engage with that, then I will let you know after it is well underway to make sure I am in fact making consistently deliverable progress on it.

#8

Thanks for this wonderful learning resource. I know many newcomers start with Grik TiddlyWiki.
One suggestion I may have for scripting is a s below:
TiddlyWiki is highly backward compatible, so it works with features invented in 2004 and those in 2024. The official website started to add the deprecated tag to discourage people using them.
For a new learner and basic/intermediate level of Grok TiddlyWiki, I would recommend to stick to a clean subset of TiddleyWiki (frankly I mean 5.3.x+) and teach newcomers with a good scripting style.
The parametrized transclusion has changed the game and I would only select this as my baseline and would select features introduced afterwards.

For example, I would remove the $macrocall and only discuss $transclude. etc

Wish you best of luck with Grok TiddlyWiki

#9

Teaching the newer syntax (like $transclude and \procedure instead of $macrocall and \define) is generally the right way to go.

However, people will inevitably encounter many existing TiddlyWikis that use the older $macrocall and \define syntax, which they will still need to understand.

I suggest that rather than completely expunging those explanations from GTW, they could be moved to a “supplementary chapter” or “appendix”, which frames them as “older equivalents” to the newer syntax, as well as explaining their unique syntax differences, such as the use of $(var)$, $param$ and <<__param__>>.

By doing this, it should hopefully allow newer TiddlyWikians to comprehend older wikitext coding that they find “in the wild”, so they can still make sense of what they see.

-e

7 Likes
#10

I’m with Eric here.

I think especially $macrocall will not go away. It’s meaning is much clearer than $transclude $variable – It can define in 1 word where the new syntax needs 2 words – So there is an advantage if the readability of the code is “a thing”.

Also \define will not go away. I personally prefer the usage of \define textString() Some text to be used somewhere over \procedure textString() Some text to be used somewhere

The resulting widget-trees of define and procedure are 100% the same.

The transclude-variable version of a macrocall will be slightly smaller in memory footprint and a tad faster in execution. macrocall in the end will be converted to transclude-variable widget. But there is a “macrocall wrapper” widget in the memory and the execution pipeline.

So if performance is a thing the new syntax has an advantage here. – it depends

5 Likes
#11

Slightly related, are you planning on creating a part 2 or part 3 for this video: https://www.youtube.com/watch?v=uf5XV99YqMc (Inside Grok TiddlyWiki, Part 1: Architecture & Philosophy)?

1 Like
#12

Thank you for planning to update Grok TiddlyWiki. The current version is a valuable learning resource and a vast source as reference without which I probably wouldn’t persevere with TiddlyWiki. That’s why I consider that a donation would be the least that I could do for you (and this is what I have done).

#13

I suggest that rather than completely expunging those explanations from GTW, they could be moved to a “supplementary chapter” or “appendix”, which frames them as “older equivalents” to the newer syntax, as well as explaining their unique syntax differences, such as the use of $(var)$, $param$ and <<__param__>>.

Very true! A Supplementary chapter or appendix is a good idea!

#14

Not part of this project, but I still do hope to eventually!

1 Like
#15

I’d be happy to help by reviewing the new book. I used the current version as a great start to learning TW around 2 years ago. I have finished reading it systematically chapter after chapter around halfway through and then I went off to experiment by myself, occasionally going to selected chapters further up in GTW. In any case, GTW has achieved its purpose of being a great detailed tutorial to TW.
If the point of view of a not-novice-to-TW-anymore is useful to you, I’d be happy to help. I’m up for reviewing the new/revised chapters. If time allows, maybe the whole book, but I can’t promise that.

#16

Sounds good, it definitely would be useful! I’ll let you know when I have more details.

1 Like
#17

I have a similar experience as described by @vilc and would happily review and provide feedback if you need it😊