Documentation tiddlers on TiddlyWiki.com in need of work (please contribute to the list)

[CodaCoder]

@Springer

It feels like an insider’s level of fluency about matters like this affects a great deal of the documentation. That is fine for the “getting it down” phase of any project, but translation for “the rest of us” will avoid lots of perplexity.

That, ladies and gents, is UX. UX belongs to the user, an embodied experience taken as a whole while using the product/service.

In my other life, I go on and on about this, having to cut away the fat from a lot of online BS about this topic:

“Wow, that’s a great UX!” No, that’s a UI.
“I’m a UX designer.” No, you’re a web designer (if anything).
“We improved the UX.” How? And where’s the feedback? Feedback will “prove” the user experience is good… or not. See https://www.youtube.com/watch?v=9BdtGjoIN4E

@Springer: can I have permission to cherry-pick your text for use in my day job?

[Springer]

Bumping this thread. I’ve gone through the wiki list at top, and found a bunch of cruft (stuff long since resolved), and initiated a couple PRs myself around easy fixes (see post below for encouragement to step up and try it).

I’ve set up details widgets around each unresolved issue in the to-do wiki at top. Let’s keep it super-easy to see the big picture of to-do requests. You can decide which details you’re curious about, and open the details as needed.

Issues that seem resolved, to my eye, I moved from the first wiki post (the “to do” list) to the second (resolved).

Having the new v5.3.4 released, this is a great time for us to pull together and see where the documentation is still in need of repair.

Despite some of my own posts earlier on this thread , this thread should stick to straightforward fixes within existing documentation tiddlers and/or super-clear small additions — “low-hanging fruit” that someone with a spare bit of time (and access to GitHub) can patch up.

For issues that require significant new technical text — or coordinated decision-making and judgment calls — my understanding is that such issues may warrant a separate discussion thread.

[Springer]

Let me add also:

As someone who is NOT super-fluent in GitHub, but who does have account there, I want to encourage other documentation bench-warmers to get off the sidelines.

It’s refreshing to shift from just complaining here to actually fixing the stuff that’s easy enough for me to fix . (I’ll still raise issues here when the “how” of the fix is too hard for me.)

You, too, can help improve documentation!

If you invoke edit-mode for a tiddler at tiddlywiki.com, you’ll notice there are TWO alternate methods suggested in a strip along the top. Both require a GitHub account, and the docs-pr-maker also requires a one-time GitHub token (which requires only a couple extra clicks).

I’ve now tried initiating a PR through each method. Compared to editing the GitHub code directly, I find the docs-pr-maker approach to be more powerful and intuitive:

• You can see right there (in a cloned tiddlywiki.com interface) how your revised code will look
• You can save a draft if you’re not ready to finish your suggestions all in one sitting.
• You can make related edits to multiple tiddlers as part of one request. (Still, you should not bundle edits that are not related, so that the approval process remains granular.)
• Once you submit, you’ll get a link that enables you to return to your PR request and make further tweaks, which does not seem so easy to do from within the GitHub commit process.

On the whole, this docs-pr-maker approach helps you feel confident about putting your suggestion into the approval pipeline.

Thanks to @saqimtiaz for setting it up and empowering the community this way!

[saqimtiaz]

Added the need for a documentation tiddler about CSS selectors to the list.

[twMat]

I’m not sure how to even phrase the heading for this “doc need” but I’d think it belongs under the existing “Provide examples for the ButtonWidget”?

Sometimes the order in which actions are executed, including the setting of field values, is critical. In the ButtonWidget, actions and setting of field values are executed in this order: <$button setTo=2 actions=3> 1 </$button>. Maybe message should be in there too (ref)?

[vuk]

I am reading https://tiddlywiki.com/#Installing%20TiddlyWiki%20on%20Node.js and I am noticing that install instructions there are very generic.

For example, for Debian:

apt install nodejs

This means “install whatever nodejs version is in the repository”.

Is there a minimum nodejs version requirement for latest stable TiddlyWiki version (the fresh released 5.3.7 at the moment of posting this) to work fine? Is there a documentation tiddler that contains this information?