Nailed. 
Positive thinking is the way to go guys! Huberman labs on mindsets!
Documentation does exist, it’s pretty good, just not perfect for everybody ….yet. And if we don’t like it we can always ask for our money back, right?
As the prolific @TW_Tones said “the best way to improve documentation, is to do some documentation.” @pmario and @saqimtiaz have kindly made it possible for anyone to contribute to the docs with these 7 Steps to Improve the TiddlyWiki Documentation, so that’s what I’ll try to do over Easter and make a pr request with this small suggestion. After that I’m going to try to read and understand the bleedin manual!
Best wishes
Sometimes, one may be just lucky enough to lead a critter to water, but if it ain’t gonna drink, then kind of a fool’s errand.
Maybe stubborn mule am I to keep thinking the process and the chosen tool is the problem. (To think otherwise, then subpar documentation symptoms are a people problem, and I’d rather not think that.)
Proof in the pudding either way.
Paraphrasing the gist of the OP:
I agree, the doc examples would bring more value if they were about filtering rather than about filters.
If the users are guided with actual use cases, using the ListWidget, they will probably more easily get a general understanding of filters - i.e that translates to other contexts where a filter attribute is used.
In fact, the distinction between a “list” and a “filter” is not clear: What even is a list that is not a filter? It is an oxymoron. “To filter” intrinsically means “to list”, and vice versa, so specifically using the ListWidget makes sense because . All(?) other widgets with a list attribute do further manipulations with the output but the ListWidget only presents the output and is therefore the “minimal” use case of a filter.
…
Overall, I think a nice balance in the docs would be if the docs are framed as “reference” but all examples in the docs should be about doing rather than just informing. Presumably, someone looking at the example does so because the bare bones reference fact was not enough.
1 Like
I agree in the sense that IF you copy an example it should produce effects in a destination wiki. Otherwise it is a copied example of nothing,
That said, I don’t think the documentation for TW should support every example fully … MERELY, that when you offer code to copy it should function without extras to DO something.
Just a comment
TT
1 Like
I agree with @saqimtiaz . I have doubts about it.
Change examples or add a tip notes about how/where we can use a filter? How could we show this notes? How could we change the examples without losing attention in the use of filters?
I don’t know if it is good idea use listwidget in examples. I think the filtered transcusion could be less complex to understand for newcomers.
I’m sure the guys actually doing the documentation go nuts when they see questions like these. Sorry documenteers! I’ll try and do a PR with this suggestion, unless anyone comes up with some specific code that would improve on my cack-handed efforts. If you actually try pasting this 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 on filter operator example tiddlers, allowing clipboard copying of a list widget example from filter operator example tiddlers, but only when you click the ‘try it’ button. It doesn’t change the display of the existing ‘bare bones’ filters at all. Win-Win!
<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>
If you look at the suggestion as more of a layout issue there’s nothing to stop a whole range of examples and explanation being included in that space. There is a lot of ‘real estate’ there, but it is way beyond my abilities to know how best to populate it. If only a ‘comments’ widget could be dropped in there, then users could add targeted ‘tips’ organically, and the docs would just grow. But I suppose that’s not far off being a forum!
Best wishes
Cutting a long story short.
I do think if you provide an ability to copy code for an example it should, in a destination wiki, once copied, DO something.
I do understand that is not always possible as a local example may have dependencies on local stuff to work. But in those cases I don’t think giving a “copy-to-clipboard” button is good. It is confusing until you better know what is going on.
Side comment, TT
Good point TT. Maybe a proviso of some kind - ‘try here on tiddlywiki.com to see results, or adapt the example to use with your own wiki and data’. Sounds a bit wordy - economic layout would need to be considered.
I’ll try the PR route and see what comes back. As @Mark_S. said, if some examples break then it may be a non-starter. That ‘try it’ button is intriguing though!
Best wishes
1 Like
I just want to put a different position. I am all for working examples and believe tiddlywiki is the best place given the content to work with. Alternatively an optional plugin of examples and test data would be good as this need not overload the main site, and be installable on empty.
However my key interest is template code that has place holders like tiddlername, fieldname, tagname and varname with each common form of the use of a macro or widget for quick copy and paste into my own code. To me this is much more valuable than working examples because its a faster path to experimenting on my own wikis.
The key advantage of optional plugins is the reduced complexity of updates and contributions with less impact than in public websites, increased transferability, reduced size impact unless wanted, removability and the upgradeability through updates.
1 Like
Came here to say this but of course it’s already being discussed. As a self learner I rely heavily on examples to help me understand the instructions and when you can’t copy paste an example and have it workable and playable with it’s not very useful. The filter documentation gives examples of how to use the operators but does nothing (as far as I can see and I miss stuff all the time) to say where or in what context those operators are used.
An example should show context. Personally I learn mostly by backtracking through something I don’t understand but without any sort of contextual example there is nowhere to go. The context also provides a reminder for infrequent ‘coders’ like myself who might use tiddlywiki for a specific purpose for a long time and just need some prompting when trying something new.
I think instead of a ‘try it’ button it would be more helpful to describe a working example and say ‘create a new tiddler and copy and paste this code into it to see it work’.
1 Like
I find running filter syntax through the Filter tab in AdvancedSearch to be a helpful way to test out the filter syntax.
I also suggest if you make a filter, to store the filter syntax in a field of a tiddler. That way you can separate the filter syntax from the other parts of formatting. See this attached example of AllTiddlers, which is a very simple example, but you could modify the filter field to use as an experiment.AllTiddlers.tid (164 Bytes)
Good Share, but I noticed the macro call was not closed
Was <$macrocall $name=list-links filter={{!!filter}}>
<$macrocall $name=list-links filter={{!!filter}}/>
unlikely to have any effect until more in tiddler