Ugly Wikitexts Ugly Rules: Where is the Best Practice?

#1

I have written already about Good Practice in TiddlyWiki (Wikitext scripting). But I see Q&A and code patterns in the forum which is a mixed of old and new WikiText.

We know wikitext grows in an organic way, and there are many solutions to do the same thing in TiddlyWiki. One reason is that the old features and new all work for the same problem. While this is great, but mixing those rules create ugly and difficult to understand wikitext. Then newcomers start learning Wikitext and soon they complain learning TW is difficult and the syntax is confusing.

Suggestion:

  1. In the official documentation we need to emphasis on this.
    1.1 Encourage using new features,
    1.2. link similar feature and tell which is more recommended.
    1.3. Use the obsolete word whenever possible
    1.4. Update the examples considering good practice
  2. Superusers can advise by commenting on solutions given in forum
  3. We need more tips and tricks and examples to teach good practice
3 Likes
#2

I will participate in this. Once again we need to start with a list of cases that fit in this category.

One approach is to review all release notes for changes that have this impact. Itvwill usualy also indicate a gap in documentation and examples because changes are often not worked through in much detail.

2 Likes
#3

Sadly … This would be a full time job.

#4

It would be. Certainly after 5.3.0 it will be a monumental task to raise my wikis to the new/improved wikitext. If I write new stuff, I’ll try to introduce the newer wikitext, but otherwise, if it aint broke…

There’s also the historic inertia present in the older standards – that’ll take time to dissipate, I imagine.

2 Likes
#5

Yes, “Historical Inertia” can also be considered “pragmatic and efficient”.

Because we are set on maintaining backwards compatibility anyway, the use of pragmatic older approaches should not be discouraged, but newer and smarter methods presented, so they become the new “pragmatic and efficient” way to do things, gradually supplanting the older methods.

  • There will be some older methods that should be replaced for various reasons and we need to start with these and showing the newest “pragmatic and efficient” ways.

Have a look at the existing $genesis widget documentation and all it does, is tell you a more verbose way you can do something, somewhat trivial, you can already do in other ways.

  • It seems to assume the reader will see the value, I doubt they will in 90% of cases.
  • The documentation provides no reason or justification for change (even if there is)
  • Supporting and developing TiddlyWiki is a full time job, one split across multiple members of the community.
  • But it must be done
  • Starting by tackling the following in the following order of precedence
    • Improving the documentation
    • Improving the examples (pragmatic examples, not symbolic and impractical)
    • Sharing the new ways when the old way is a problem (and explain why because it is often contextual)
    • Sharing the most “pragmatic and efficient” way to do things new or historical.
1 Like