Documentation examples - small macro change suggestion

#1

Would it be possible to make an adjustment to the macro used to provide examples on the official tiddlywiki.com documentation?

If you cut and paste the current given examples into an empty wiki they won’t do anything because they are missing half the required syntax. Very confusing for new users and beginners. The current examples are ‘cut down’ to their bare filter elements.

[bare filter]

Instead of

<$list filter="[bare filter]" />

Would changing this macro in $:/editions/tw5.com/operator-macros work?

\define .operator-example(n,eg,ie)

On line 3 in the first reveal, from:


`$eg$`

to:

<$list filter="$eg$"><li><$link><$view field="title"/></$link></li></$list>

Would this provide users with full code examples that work when cut and paste into their own wikis, or does it fail with some types of documentation example?

3 Likes
#2

Give you give an example of one that doesn’t work?

#3

That is because they are examples of only filters, not anything else. Filters are used in many contexts, the $list widget is just one of them.

#4

I now understand what you’re saying @saqimtiaz , just, but I wouldn’t have understood it as a new user or even advancing beginner.

I remember as a beginner going to the docs, finding the operator that I thought I needed, finding the examples, cut and pasting the example and then scratching my head because it didn’t work. Next stop - searching the forum for examples that did work. Very frustrating for beginners.

@Mark_S I’d have to say none of the examples work, as presented. I see that filters can have different contexts and the $list filter is only one, but new arrivals don’t know that.

What about adding the suggested alteration as a toggleable option for cut and pasters - ‘this is one way to do it, there are others’? New users would then get to see something happening ‘out of the box’ when they try it on their own wikis.

#5

I wouldn’t expect a beginner to be intensely interested in filter operators per se until they had read about and understood filter expressions.

1 Like
#6

I can only speak for myself, but when starting with a new toy the last thing I do is read and understand the manual. :upside_down_face:

I suppose my question is really ‘would the suggested macro ammendment work for all examples in the docs?’
If it does, would it be useful for beginners if presented appropriately? (2 questions!)

Best

#7

Then why are you looking at the technical details for filter operators?

My guess is that it will break for at least some of the examples. Having to track and check several dozen examples because a hypothetical user might understand it better is a big ask. But anyone can make a PR, so … who knows.

If it was me, I’d make a simpler example that just used the list-links macro, rather than all that HTML that’s hard to parse visually.

#8

@Watt
I have often thought the TW examples are too dense/multi-layered. It would be much better for everyone if leaner examples were produced where everything necessary to exemplify an item were either in the tiddler itself or no more than a couple searches/clicks away.

Obviously, for more complex use cases, a series of transclusions might be required – but only if transclusion is the topic under discussion. But macro>macro>macro wrapping the great unknown is bewildering.

$0.02.

#9

ll;

@Watt thanks for letting us all know what you perceive to be a gap. It is important for the improvement in accessibility to tiddlywiki that we hear all voices.

Not withstanding my considered reply below I think we can find some better resources for you to lean more about using filters, as tiddlywiki.com is a somewhat brief documentation of syntax.

In essence I can see how tiddlywiki.com’s use of the “documentation macros” typically starting with “.”, adds great confusion, if you are trying to find working examples. See Documentation macros. My recommendation is steer clear of these, even I, as an experienced tiddlywiki designer, I avoid these (because the self documentation is poor), and I believe a barrier to contributions.

I do think it important that while we try and cater for all learning styles we also make sure the documentation remains clear and focused on addressing key issues without getting too complex.

In a similar vein to your suggestion rather than working examples I would like to see all macros, widgets and filters in the documentation have “generic” code examples of each of its major forms so we can quickly copy a snippit of code for use in our own wikis.

  • However to be generic these would need key parameters to be modified before they can be used.
  • If pasted into an “empty tiddlywiki” they will not have much value as the data is not present for the examples to work with,
    • Note: This is similar problem for your suggestion**.
  • We must note however tiddlywiki.com has a lot of content and thus can be a useful place to have working examples, although these working examples may not work in your own wiki as is does not have the same content.

However there are ways around these problems and my latest view point is the idea of;

One or more plugins you can install (no save and reload required) on tiddlywiki.com (or a copy of the whole tiddlywiki.com saved locally). That displays additional content for the tiddlywiki enthusiast and other user segments.

Examples include;

  • My desired code snipits for reuse in wiki designs
  • Working examples as you are asking for without using the aforementioned documentation macros.

I believe to support what you are asking for we could have the optional plugins as I suggested or we could also provide one or more plugins containing example data against which to “run” examples.

  • Imagine a plugin with some basic e-commerse, world fruits, geological epochs and other data examples, possibly usable in their own right against which you can test snippits and examples.
  • By having curated sets of example data such experiments can take place in your own or custom wikis without the complexities introduced in tiddlywiki.com by its need to satisfy other objectives.

I know this may seem a little off topic to your request but I also hope it throws a little light on why it is “as it currently is” and how it is all (and always will be) a work in progress.

  • It is for this reason we need people like yourself to voice their ideas and “complaints”.

Thanks for your contribution.

1 Like
#10

I think your request is valid. I would also like to have a “copy example to clipboard” button, that creates usable code, similar to the one you describe.

5 Likes
#11

I do think the filter operators tiddlers are rather terse. The way the examples are separate from the tiddler is different than the way, for example, the ListWidget tiddler is written, where is description in between the examples to provide further detail.

1 Like
#12

I’m with you on this - copying and pasting from the docs to find it doesn’t work and then searching the forum to find the rest of the expression.

1 Like
#13

I still class myself as a beginner because I haven’t devoted the extra time I would need to really get my head around things, but because I’ve been using TW for a while, I have more advanced aspirations for what I want the wikis to do and that’s when I’ll then look round for solutions which invariably relies on cobbling things together which I don’t fully understand and copying and pasting other’s solutions. So I think ‘beginners’ probably come in all shapes and sizes.

4 Likes
#14

I think chances are high, that we can create a whole wiki for every filter operator and we still won’t cover all the possible usecases.

Grok-TiddlyWiki has a good introduction, with some questions and answers linked to it. Grok TiddlyWiki — Build a deep, lasting understanding of TiddlyWiki … But it also only shows the filter string and no bigger context.

There may be better links in Grok-TW, but I don’t know it well enough to point them out.

#15

Thanks all for the discussion - this is truely a great forum!

The docs regularly take a kicking but they’ve done the job for so many users so far - maybe I should have floated this as a constructive ‘enhancement’ rather than a negative ‘alteration’? Positive thinking can move mountains (of documentation)!

Instead of changing the existing macro what about keeping it as is, (but maybe labelling the existing ‘bare bones’ examples ‘Pure Filter’) and just add a second macro (maybe labelled as ‘List widget example’ with a copy to clipboard button)? Anything that produces ‘working’ cut and pasteable code would add clarity imo.

Is it bad to have too many examples?

The addition could possibly include the Learn more about how to use Filters link that already appears on Filter Operator doc tiddlers. Maybe even add another link, ‘Beyond list widgets’? Turn it into more of a pointer for learners.

The beauty of this approach is that making a few changes to the macros on one page adds a lot of value across all the documentation for minimal effort. (imo!)

That $:/editions/tw5.com/operator-macros page seems to hold an awful lot of documentation power! Thanks to @Charlie_Veniot for pinpointing it in another thread.

Of course none of this works if the changes would break existing examples.

In that case would a coding challenge to add a filter to the suggested macro which id’s and conditionally hides the proposed ‘enhancements’ where it doesn’t work make for a fun Easter hunt?

Best wishes Tiddlywikians, Happy Easter.

2 Likes
#16

Well, I am extremely opinionated about documentation (organization and process). Documentation is one bit of my career bread and butter, and I am easily unsatisfied.

Probably best to not throw any appreciation my way, because as of that referenced thread, I decided to remove myself from any conversation involving TiddlyWiki documentation (this reply the exception?). Best for everybody.

Instead of yanging (edit: by that I do mean me, because I’m so opinionated, and not implying other folk who want legit help from the documentation) about TiddlyWiki documentation, I focus on continuously honing my approach to documentation with my BASIC Anywhere Machine project, in particular the Machine (IDE etc.) TiddlyWiki and the Programming Reference TiddlyWiki.

Of note, take a peek at how the Programming Reference “sucks in” programs from the machine, so that when looking up a BASIC statement/function in one TiddlyWiki, the documentation includes sample programs from the machine (that use the statement/function) in the other TiddlyWiki and provides a RUN button so that you can see the program running while viewing the documentation for the statement/function of interest and the program source code.

So every single thing exists once in some TiddlyWiki, and every single thing is view-available from any TiddlyWiki.

I love that kind of stuff:

Rock’n roll.

#17

You have definitely read and understood the manual @Charlie_Veniot ! The Basic Anywhere Machine pushes envelopes further than my postman at Christmas, please don’t blow an opinionated gasket and disappear from the lovefest that is tiddlywiki.

For the record here is some crude code that can be pasted into $:/editions/tw5.com/operator-macros on tiddlywiki.com, immediately before the

</$reveal>
</$list>
\end

of the macro defined as .operator-example(n,eg,ie).

It adds the ‘enhancement’ unobtrusively to the ‘try it’ button, allowing clipboard copying of a list widget example on filter operator example tiddlers.

<details><summary>more...</summary>

<$macrocall $name="copy-to-clipboard-above-right" src="""<$list filter="$eg$"/>"""/>
`<$list filter="$eg$"/>`
<p>
Learn more about how to use [[Filters]]
</p>
</details>

Best wishes

#18

That’s the kind of warm fuzzy to make my week.

For anybody who can handle the process and give the documentation some love (even just suggestions posted here in TiddlyTalk), that is a substantial gift.

This forum also offers up a feature for “wiki articles,” which folk seem to like. (Not my cup of tea. Forum and wiki and blog, I like neatly separated. Like a kid who doesn’t like peas touching the potatoes, nor the potatoes touching the chicken fingers. Yeah, cognitive disability over here, and no OCD diagnosis? Go figure …)

#19

Yes I believe it is better to highlight areas of confusion. Even as someone like myself who has been using TiddlyWiki for quite awhile I find the way the documentation approaches certain topics, in particular filter operators rather confusing. It is absolutely possible to use TiddlyWiki for awhile and still not understand the many sophisticated methods of transclusion, filtering, and listing that are possible (new features are constantly being added too and best practices might change)

It is important to think in terms of a certain “tiddly” philosophy, namely to compose your content in such a way that enables re-use, “dividing information into the smallest semantically meaningful units of text”. The Filter Operator tiddler uses many of the advanced techniques TiddlyWiki offers in the way it generates the table listing the filter operators, even though it is hard to copy and paste this into your own wiki.

#20

Just when I think I’m doing well at keeping my nose out of “TiddlyWiki Documentation” topics, I get a random thought out of nowhere.

I think the biggest problem with TiddlyWiki documentation is the use of TiddlyWiki for documentation.

A case in which “eat your own dog food” is maybe not such a great idea.

Two points, both in regards to multi-user/community collaboration:

  • technical setup / architecture
  • documentation process

Both of these are complicated, convoluted, when using TiddlyWiki for collaborative documentation (or content/KB/whatever).

If it can all be done easily, I have no knowledge of that. Because I cannot find documentation about making it easy, and with my own experience thus far: not easy.

But if you are like me and like hacking away at things for the joy of it, it can be done.

I know how to go about it with TiddlyWiki. But do I want to? Not so much. It was fun figuring it out as a brain-age game, but would I do it again? Otherwise: nah. Did it once, don’t particularly fancy doing it again. Well, maybe for the right $$$'s ?

Although there probably aren’t many folk who find joy working on documentation, I think decent documentation depends more on easy technical setup/architecture and easy process much more so than the number of collaborators.

I think quality documentation might be better served by documentation managed with a tool that makes process much easier, leaving TiddlyWiki.com purely for the examples of how to do this/that (which is documented somewhere else, which points to those examples at TiddlyWiki.com .

Something like that. Too many intertwingled thoughts in this sponge…

These are just some of the scattered thoughts I have on the whole thing.