Hear hear! My biggest challenge with the documentation is finding only flat and simple examples, then feeling disoriented about how in practice to get the filter (or procedure etc.) to work with whatever kind of variables or dynamic references might be useful in practice.
While the post did work in the other thread, I did move it, since longer discussions that may follow, would derail the OT (original thread).
I think you are right. But finding the right examples, that are “easy” to understand and are “also useful” is hard. Especially if they affect the wiki itself.
Since the introduction of the test-case widget, it is easier to create new tiddlers, since they do not “pollute” the main wiki store anymore.
So it is OK to “spam” the testcase with new tiddlers. That’s what the new Action-widget examples do.
It’s OK to hit the “Create tiddler” button there a hundred times, since the test-case store does not influence the main wiki.
The same thing is true for examples that need a “specialised setup”. Test-cases can have compound tiddlers as input. So it is much easier to create a test-environment that exactly fits the functionality, that should be shown.
So why don’t we have testcases for every filter operator? … Well because there are many of them.
Creating filter examples that actually make sense needs a lot of work. So resources are the main problem here.
We need community contributions.
@saqimtiaz did create the TW PR Maker edition which allows us to create documentation contributions using TW itself.
But it seems the community does not even test it, to give feedback. → Positively written feedback even if it highlights shortcomings is encouraging for devs → But without feedback there is no real motivation for progress …
So it also seems to be a bit of a “chicken / egg” problem.
I don’t know …
This is a fantastic tool, and I have contributed in this way! However, it was months ago, and I recall that it required a bit of a learning-curve, and coming back to contribute more will require another chunk of time in orienting to the process.
This is exactly right. I really like to create intuitive examples, well-explained. This does take time, as you point out!
Could we take the problem the other way round?
We have many prolific contributors in the community, who share their code and plugins.
I’m sure these contributions are filled with very smart pieces of code which might be reused as examples in official documentation!
And maybe the effort needed to contribute docs would be smaller if the contributor has already used an operator, a widget or a pragma to fulfill a real world use case?
Fred
1 Like
yes, let’s start with examples using the forms here
I agree but as being said;
We choose to document tiddlywiki and do the other things, not because they are easy, but because they are hard, because that goal will serve to organize and measure the best of our energies and skills, because that challenge is one that we are willing to accept, one we are unwilling to postpone, and one which we intend to win.
That’s true.
we need data
I have long argued we need some generic test data around which examples can be written. I still have trouble making use of the test case widget.
- example data may include fruits and mocktail recipes
- such data sets could be used for others to use when sharing problems they are trying to solve independently of private data and should include contacts and others.
- not withstanding the above tiddlywiki.com doco can also be used as test data but needs to be clearly seperated in examples from official document curation.
I’d love to, but I fear that “very smart pieces of code” are usually not what we want in examples.
The sort of thing I am envisioning is replacing a few examples in this:
with ones using different braces:
But, as @mario points out, this is a lot of work, given the number of operators we have, and it would probably involve creating at least a few more documentation macros.
I would rather not use the testcase widget for these, but a variant of it dedicated to documentation examples. I think we need a few more primitives to access the tiddlers inside a CompoundTiddler, similar to the ones we use for plugins (plugintiddlers and subtiddlerfields) so that we could build out such a beast.
And therein lies the killer (in a bad way) in my view. I’ve said it before and I’ll say it again, those doc macros do nothing to help new users, let alone me. If I click edit and see those, I close the tiddler and move on. I simply don’t have time to dig any deeper into something I don’t understand and know for sure I’ll never use myself. 
<rant>
Hear, hear to that, too. And what you (@Springer) said about Saq’s GH/doc thing – too steep an on ramp, for me. I used it once… worked great. Next time I wanted to contribute (2 maybe 3 years later)… slam. Brick wall (read learning curve). I just don’t have time for it. It should be possible to help out with ease each time I choose, even if each episode is separated by months or even years.
</rant>
Understood, but without them, maintenance gets much harder. And we’re having a hard time keeping up as it is. I don’t have a great solution, but it’s a real problem.
I think it was easier to use only sporadically when GitHub tokens didn’t expire, or had very long expirations. Now, I think they default to a month and don’t allow anything over a year. This means that coming back to the tool in even a few months, you probably have to go back to the beginning again, and generate a new token. After that, I find the tool relatively easy to use and really nothing short of brilliant.
But I’m a regular git/GitHub user myself, and I find it just as easy to contribute to the docs the same way I would contribute to anything else. So I don’t use Saq’s tool often.
Ditto. But the point I’m making is, the TCO is too high (for me). That may change in the future but my crystal ball hasn’t worked right for ages…
I’d not seen this tool before, so looking into it for the first time. The link it sends to for token creation does indeed default to a month, but allows options up to and including no expiry
Ditto. It should absolutely be possible as a volunteer contributor to community resources to contribute with ease. From my personal perspective, that would require that community members for whom said resources are created provide feedback on what does and does not work for them in a timely manner, no matter how succinct said feedback might be.
I personally use 90 days but there are options. IMO that one can not be the barrier to avoid using the PR-Maker edition.
A great resource for learning filter programming could be one day what Jeremy worked on in Filter inspection for debugging by Jermolene · Pull Request #9003 · TiddlyWiki/TiddlyWiki5 · GitHub because of its useful visualization of complete filter expressions. Any help to get this PR moving forward would be valuable.
Due to the way it works, I prefer the debug-log Filter for debugging live code, though.
2 Likes
I hear you. Truly. However, “in a timely manner” is not possible since the crux of the matter is that, considerable time has passed since the first use and (aborted) second use.
I wish things were different, but honestly, I don’t think there’s much that can be done. Github is as Github does and all that. If and until I’m “in it” ~24/7, (i.e. gaining and reinforcing “muscle memory”) that will remain the case, I fear.
And just to be clear, @saqimtiaz, there is NOTHING wrong with the tool, nothing that you need to “fix” or otherwise. My failure, if there was one, was to not record my screen and store it safely for “next time”. Had I done that, things would look a little different.
I think I wrote:
… → Positively written feedback even if it highlights shortcomings is encouraging for devs → But without feedback there is no real motivation for progress …
Folks. Developers are humans and
“… slam. Brick wall (read learning curve). I just don’t have time for it. …”
is not really the type of actionable feedback we can work with. – At least I have problems with it.
I thought more about something like this:
@saqimtiaz – Thanks for you time you put into the PR-Maker.
-
As a user, I would like to contribute from time to time, probably 2 or 3 years apart. So it should be possible to easily create a new GitHub token, since the old one probably timed out already.
-
Also I do not want to read the initial “Tour” every time I open the page, so it should be easy to directly jump into editing the content.
Just my thoughts.
- It was not feedback on the tool, as I made clear (I thought). It’s feedback on the entire process largely attributable to GitHub, not PR-Maker.
- I’ve been a developer for ~45 years.
- Last time I checked, we’re all human – so please turn off the preachy moments, they’re just as unhelpful especially when open/honest discussion is happening, IMV.
Could adding third-party comments resolve this issue? Everyone can add their own documents.