[tw5] TiddlyWiki documentation request: improve access to examples

[Charlie_Veniot]

As part of the learning process, it is really handy to see all of the TiddlyWiki goodness involved in any examples.

That is frustratingly hard to do, because many examples are the result of macro renderings.

Take the “all Operator (Examples)” tiddler for, um, example (screenshot further below):

As I look at everything there, I am not only interested in how “all” works, but I am also interested in how the “Try it” buttons work.

When I edit that tiddler to see how things work, I see a whole bunch of macro references.

That’s cool. I also have an opportunity to see how macros work by inspecting them.

But I have no idea how to find these macros.

So now I can’t easily see how those “Try it” buttons are setup.

These are roadblocks to learning TiddlyWiki things.

I’d like to request that the documentation be setup such that learners can easily discover things in that TiddlyWiki. Either stop using macros as a way to show examples (maybe replace them with transclusion templates, so that there are tiddler titles available to find things), or add some documentation to the documentation to make the macros easy to find.

Something like that.

[Alvaro]

It’s true. It is difficult to find if we don’t know how do it. In tab System of AdvancedSearch, its tiddler can be found-> $:/editions/tw5.com/operator-macrosif you enter its name (.operator-example)

Maybe it could be together the other macros in the tiddler Documentation Macros and we also say the tiddlers where are the macros.

[Charlie_Veniot]

Proximity is king. If I’m looking at it, it is good if there is something right there for me to click on.

It should be easy even for the first-time viewer of TiddlyWiki documentation to be able to click a button.

User-friendly access. Bad idea to force folk into Advanced Search to figure out where something is.

[pmario]

Go to Advanced search. Search for “.operator” (without the quotes) and have a look at the system tab. There are 2 results.

You basically can find absolutely everything in TW with advanced search, if you switch tabs.
-m

[Alvaro]

Yes, I agree. The click is better solution for learners.

[Charlie_Veniot]

Yes, I know that. I’m not asking for myself. My point is that it should be easy for anybody to learn about all TiddlyWiki features involved in any example in the documentation.

Every example is a showcase for more than the one thing the example was created for.

Not a great idea of always putting users in the position of asking where things are all of the time.

Unless that is the point: we don’t want the documentation to be so good that users don’t have to always ask questions?

TiddlyWiki allows for mapping intertwingularity (i.e. making and showing all of the relationships to all things.)

It is sad and disappointing that TiddlyWiki features are being used in the documentation, but the very usage not documented. Lost opportunities.

[pmario]

Yes, I know that. I’m not asking for myself. My point is that it should be easy for anybody to learn about all TiddlyWiki features involved in any example in the documentation.

…

It is sad and disappointing that TiddlyWiki features are being used in the documentation, but the very usage not documented. Lost opportunities.

OK. So a little bit of info for those, who want directly contribute to the TW docs.

You are right. … Documenting “the documentation” is an option, to show users what’s possible. I think the needs of the TW docs are very specific. But still – one can learn a lot from it.

We – the core devs – need help from the community if that “meta” content should be there.

There is a lot of work to do for the reference documentation. Detailed documentation “how the doc macros work” will add to the existing work that “should be already done” …

The TW documentation is a community effort and everyone is welcome to create content and contribute it.

I did create a HowTo: 7 Steps to improve the tiddlywiki documentation at “Talk TiddlyWiki”. I also did create a video series, that shows how to use it. The link to the videos can be found at the HowTo.

Discussion and feedback can happen at Talk too.

Saq, did create a “working prototype” Wiki that is online, can be modified and can create contributions, that can directly be implemented into the “living” docs at tiddlywiki.com. (Link in the HowTo)

There is a Documentation Styleguide and an overview about the Documentation macros at tiddlywiki.com … (By the way, I’m talking about those elements in the Video mentioned in the HowTo.)

Contributions to the documentation can be successful, if users loosely follow the style-guide. Nothing can be broken. It may take several iterations till something can be accepted.

So everyone, that wants to help us to improve the docs, so we don’t loose opportunities can have a closer look at: 7 Steps to improve the tiddlywiki documentation

Have fun!
mario

[Charlie_Veniot]

I apologize to everybody for suggesting something that I thought would be beneficial, because I see now there is no way to put in what I was thinking without a complete overhaul of the documentation’s architecture.

When I inspect https://tiddlywiki.com/#%24%3A%2Feditions%2Ftw5.com%2Foperator-macros, I realize the entire architecture of the thing is way too complex to change, and way too complex for me to ever consider helping out. The process was already too complex for me, and now I see the architecture is not something I can handle.

So hats off to the folk who can wrap their brains around that, because I have neither the time nor the desire to put in the effort to figure that out.