The documentation is bad

[un.ol...@gmail.com]

Hi,

I love TiddlyWiki but I hate its documentation.

Let me give you an example. I want to export my tiddlywiki to a static HTML web site, I spent an hour without success.

Google gives me

https://tiddlywiki.com/static/Generating%2520Static%2520Sites%2520with%2520TiddlyWiki.html

which tells me to use --rendertiddlers




Note that if I click on a link to the command I go to

https://tiddlywiki.com/static/RenderTiddlersCommand.html

where it is said I should not use `--rendertiddlers` but `--render`.

If so, why don't the first page use `--render`?





Whatever, what confuse me is how to use `--rendertiddlers`, I mean where to type the code?





It looks like an option of some command from my Unix point of view but maybe there is some place in my tiddlywiki I should type that command which starts with `--`. So I searched if I could change the type of a tiddler to be executable, if there is a special tiddler hidden to run that command, but without success.





Then I looked for `commands` in TiddlyWiki and I see


"A command is one of the following words, written with a -- prefix and used as a command-line option under Node.js,"




Argh, does it means I have to learn how to use Node.js? There is no other way to export my pages? Hopefully there is a link to

"Using TiddlyWiki on Node.js".

Here I find that indeed `--render` is an option of a command and not a command itself and that the main command is `tiddlywiki`.

What the hell is the program tiddlywiki? For years I thought that tiddlywiki was the empty.html file.

So there is a tiddlywiki program. How do I download it? Is there is a version for Linux? When I search in Debian packages I cannot find it.

So I am stuck and I lost a lot of time. A good documentation would have given me the command line from the beginning (at least in an exemple) and of course it would have explain me how to download the tiddlywiki program. Of course it would not suggest to use --rendertiddlers and somewhere else says that it is deprecated.

One example does not make a documentation to be bad, but I must say it happened to me more than once that I had to find help on the Internet to understand the documentation. That's a pity because TiddlyWiki is great.

Olivier.

ps: I have no idea why that mail changes the fonts from paragraph to another. I guess it is a cursed day.

[@TiddlyTweeter]

un.o...@gmail.com wrote:

I love TiddlyWiki but I hate its documentation.

The docs use a very condensed style. Its understandable in that they would get too long, too prolix, otherwise.

It is also, probably, partly, Jeremy's style of writing.

*I* find it somewhat annoying too. 

Filter operators, for instance, have a very terse mode of documentation that often leaves unclear their full scope. 

But part of the issue is  NOT the main docs. 

IMO its actually access to the supplementary materials users are constantly writing on this Goggle Group that

is the big problem.

Its is VERY difficult to FIND what you need when you need it. 

9 times out of 10 it exists.

 

Overall TW suffers, I think, from this: Knowledge is there; easy access isn't.

My 2 cents

TT

[Birthe C]

Hi,

You are right, to use the command, you need node.js.

https://tiddlywiki.com/#GettingStarted%20-%20Node.js shows how you get tiddlywiki to work with node.js. The explanation is for MAC and Linux.

I am a little confused though. If you are happy using the single file tiddlywiki, why would you want to complicate matters further?

To my knowledge there are not click and install tiddlywiki program, that will do anything anybody can think of right out of the box.

Birthe

[TonyM]

Oliver,

The community and Jeremy do accept critisisium where due but as a community we need to remember any member can contribute to improve them.

This is difficult when we look for something we do not understand because until we do we are not competent enough to improve the documentation.

The take home lesson is contribute to the docs with what you understand and ask the community for help about what you dont and when the documentation is imperfect.

on Tiddlywiki.com edit a tiddler and you will see a link to contribute to the docs.

Your post title would have been better being about the info you need than what you used.

Have you tried using the export tiddler button on tiddlers? The word command typically referred to the command line which is only relevant for server or node implementations.

Regards
Tony

[@TiddlyTweeter]

TonyM wrote:

This is difficult when we look for something we do not understand because until we do we are not competent enough to improve the documentation.

Yes. But its also because we don't provide easy access to supplementary documentation that does exist.

So I think you are wrong in the sense that every user should not have to become a detective to get off ground zero.

Just BE INFORMED where to look for help that ALREADY usually exists.

WHERE is that resource? 

Its the fact help exists already that constantly goes down the drain that irritates me most.

 TT

[@TiddlyTweeter]

TonyM wrote:

 ask the community for help ...

Right. And ask them to give a searchable INDEX to find it. 

So we don't constantly re-create the wheel :-) 

TT

[TonyM]

Tt?

I don't think anyone should need to be a detective but its important to recognise the source of such material is community contributions.

Otherwise we are in furious agreement.

Tony

[David Gifford]

To export a tiddler:

1. Click the down arrow at the top right of the tiddler.

2. From the dropdown menu, select 'export tiddler'.

3. From the second dropdown menu, select the format you wish to export the tiddler as.

[@TiddlyTweeter]

TonyM

We are not in argument, really.

It is more that PEOPLE LIKE YOU constantly document usage. Well.

But your efforts GO DOWN THE TOILET. Because a few days later how do we find them?

That, I think is the central issue. 

That we are mad to believe that new users can grapple with this Google Group, 

even though, somewhere in it, lays an answer.

Just MO.

TT

[David Gifford]

Oops, sorry, didn't answer your question correctly.

To export an entire TiddlyWiki file as a static site, you must do that in node.js.

If it makes you feel better, I went through the same hunt that you did, a couple years ago, thinking there had to be a way to export the entire wiki as static hml files from the single file TiddlyWiki. I think I eventually had to ask here, and was told it can only be done on node.js.

On Monday, September 16, 2019 at 4:40:12 AM UTC-5, un.o...@gmail.com wrote:

[David Gifford]

Now, about documentation, in my case the problem is that Github is equally confusing to me. Branching? Cloning? I avoid it like the plague, and in my TiddlyWiki toolmap I only link to demos, not to Github, if I can avoid it. (I should mention that one or two others also update the toolmap, and I don't know what they do).

So to help others overcome the learning curve for TiddlyWiki I have to navigate the equally confusing (to this non-coder, anyway) learning curve for GitHub? Forget it. Too many other things on my plate.

On Monday, September 16, 2019 at 4:40:12 AM UTC-5, un.o...@gmail.com wrote:

[@TiddlyTweeter]

David Gifford wrote

If it makes you feel better, I went through the same hunt that you did, a couple years ago, thinking there had to be a way to export the entire wiki as static hml files from the single file TiddlyWiki. I think I eventually had to ask here, and was told it can only be done on node.js.

Great. Where would the user find that GIVEN answer already, since it exists?

It concerns me we keep re-creating the wheel.

Best wishes

TT 

[Mohammad]

On Monday, September 16, 2019 at 2:10:12 PM UTC+4:30, un.o...@gmail.com wrote:

Hi,

I love TiddlyWiki but I hate its documentation.

I feel the same!

If it was not the very helpful and responsive and kind people of Tiddlywiki community I would have given up years ago!

I even think Tiddlywiki in its vanilla mode is NOT suitable for documentation (like what is at tiddlywiki.com)!

One more point Tiddlywiki Community (both developers and users) is like Google Assistant, Cortana, or Siri you need to say what you want and then great answers appear then!

The difference is here real and kind people answer instead of robots! So this is a benefit over Google assistant :-)

--Mohammad

[Mark S.]

On Monday, September 16, 2019 at 6:23:59 AM UTC-7, Mohammad wrote:

The difference is here real and kind people answer instead of robots! So this is a benefit over Google assistant :-)

<beep>I'm sorry. I didn't understand the question. Here is a list of necromancers within a ten mile radius<beep>

[Birthe C]

You are right, Mohammad but I often find it difficult to write the question. When I started using Tiddlywiki (classic) I had a good teacher, Måns. He told me, that when I was able to write the question I was not far from finding the answer myself. Often enough he is right.

You are all right about difficulty in finding stuff in Google Group. That is of course a bad thing. On the other side it is good, that when you ask a question most often you will get a friendly answer. No one loose patience because the question has been put several times before - no read the f...... manual. (I love this group for the kind and generous people in the group- each and everyone of you.)

Let us also remember that Eric Shulman offered to write the manual - and who would be better to do it. He had to have some money to take the time off to do so and tried to get funding. He did not get enough.

@Olivier please ask again.







Birthe


[Mark S.]

Not that I would disagree about the documentation, but a small bit of your problem was Google search. It lead you to a static

page that limited your other search options. In the upper right hand portion of the page it was tagged "TiddlyWiki on Node.js"

which was meant to tip you off to the context.

If you had gone to tiddlywiki.com, and typed "static" into the search, you would have seen the same tiddler listed. But you would also have

seen hundreds of other possibilities including

"How to export tiddlers"

which is probably what you really wanted.

When I'm looking for something about TiddlyWiki, and I think it's likely part of the core, my first stop is TiddlyWiki.com.

If I'm looking for something about TiddlyWiki, and I think it's likely a 3rd party resource, my second stop is David Gifford's TiddlyWiki Toolmap.

If it was easy to do, I would modify "Generating Static Sites with TiddlyWiki" to include a link at the top to the exporting files option.

However, all the documentation is done through GitHub and the methodology was changed without, ironically, a clear explanation

of how to implement that change. Working this way is like building a ship in a bottle or mining a mountain with a tooth pick.

Like others, I had started my own documentation for TW, but then realized that it would be an enormous amount of work, and

would only have whatever visibility it happened to gain via Google.

Good luck!

[@TiddlyTweeter]

Mark S.

Good practical post.

My take on it: we need a consolidated search mechanism better honed to finding things over  the major source materials.

TT

[Aidan Grey]

As a business analyst for the last 20+ years....

Expecting community documentation NEVER works, not in a business and def not in the tech community (it does work well among fandom, but... That's not the same).

So what is needed, imho, is a committed team to address and collect documentation, and that would maintain going forward. They'd need to be people with skill at writing use docs too (to address some of the too terse issues). 

I think someone else basically said the same above, and this is my agreement. Without _someone(s)_ willing to manage this, it's never going to happen.

--
You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/9e876507-16b6-4db9-a7d4-6da68e37b117%40googlegroups.com.

[Mohammad]

If I'm looking for something about TiddlyWiki, and I think it's likely a 3rd party resource, my second stop is David Gifford's TiddlyWiki Toolmap.

The third stop SOMETIMES may be https://kookma.github.io/TW-Scripts/

--Mohammad

[Watt]

Group hug guys, group hug.

https://youtu.be/mgmVOuLgFB0

[TonyM]

Folks,

For those of you will the decade or so long experience with tiddlywiki you may recall that the google forums are one of tiddlywikis strengths because the policy has being ask and we will help. It does not demand you to search for your answer. I believe this approach should remain, but yes more self serve should be available. TWC used to have a tiddlywiki.org wikimedia if I remember correctly, but we have being naturally reluctant to introduce another wiki to document our wiki.

I have every intention of constantly document[ing] usage. and at least do so in my own notes.

However I have "a life" that limits how much I can commit to Tiddlywiki (to be honest already too much, its an obsession)

As my expertise increases the more confident I can see both the questions and the answers, and thus contribute to the documentation. But it also drives me to participate in issues, changes and discussions for the development of tiddlywiki. A lot of us are contributing to the future of tiddlywiki rather than the present moment documentation of tiddlywiki.

As I said I and many others have considerable resources and documentation that is not necessarily polished sitting offline. Mohamad of late and others "in history" have built fantastic resources and people should be encouraged to leave the forum and search on the open internet for "anything tiddlywiki".

The truth is information ages so unless it is collected into a single repository that is maintained it ages and looses its accuracy.

Some regular posts to the forum on how to contribute to the documentation and core would help promote participation.

Regards

Tony

[A Gloom]

Concerning the single file/node.js confusion-- it's easy with the documentation to end up on node.js pages when you're looking for single file info-- I believe most of the node.js tiddlers are tagged "TiddlyWiki on Node.js".

I spent the last year learning TW mainly from a combination of official documentation, several users' reference wiki's, this group and lots of experimenting-- all too often too stubborn to ask for help. It is well known and acknowledged that the documentation is confusing or lacking (this is a group of individuals that put out the software, not a company) and supplemental documentation (from users experience) is scattered and often not in the proper format for official documentation and users' contribution to official documentation is what it is. 

I still have to track down more of the users' reference wiki's but I have a few of em in the searching high n low section of my test bed wiki (where I can initiate searches of them, display a few of them right in my wiki)

[Suzanne McHale]

Yes, I had the same frustrating issue! Using Node.js to generate singular Tiddlys is not a beginner-friendly method (see an old post of mine here).

[Olivier]

Thanks for your answers, it seems I am not the only one confused with the doc (I exclude those who trust so much in the doc that they told me to look at pages I cited in my initial mail :)

Since yesterday, I found out what is Node.js and that to install tiddlywiki (the program) I should first install Node, so on Ubuntu it would be

apt install npm

npm install tiddlywiki

Not that difficult to explain but if you don't know it, you waste hours.

So that bring us back to the doc, how could we improve it? Could I put that information in the page "Using TiddlyWiki on Node.js"? Could the doc of TiddlyWiki be a wiki that anyone can edit?

Olivier.

ps: I still don't know how to make a whole static web site from my TiddlyWiki. The best I could achieved was to create one HTML page per tiddler but links do not work. I cannot go from a page to another. Here the command I used:

tiddlywiki.js --verbose --load mytiddly.html --render '[!is[system]]' '[encodeuricomponent[]addprefix[tiddlers/]addsuffix[.html]]'

--
You received this message because you are subscribed to a topic in the Google Groups "TiddlyWiki" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/tiddlywiki/OFgLprXtOk0/unsubscribe.
To unsubscribe from this group and all its topics, send an email to tiddlywiki+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/e1bf7ef3-8f72-4a54-aee5-c61d3b0555f2%40googlegroups.com.

[Olivier]

I just succeeded to export to a static web site but with the old option, I cannot do it with the new one.

~/node_modules/tiddlywiki/tiddlywiki.js --verbose --load mytiddly.html --rendertiddlers '[!is[system]]' $:/core/templates/static.tiddler.html static text/plain

[un.ol...@gmail.com]

I haven't seen this answer which was exactly what I needed. Thanks.

BTW there is also a page "Installing TiddlyWiki on Node.js" which is a copy of GettingStarted except it has labels. Very confusing.

Of course none of these two pages are linked from the page "Using TiddlyWiki on Node.js" nor is the page "TiddlyWiki on Node.js" except if you go to the dynamic web site and know you can click on the label...

[un.ol...@gmail.com]

On Monday, September 16, 2019 at 1:45:52 PM UTC+2, TonyM wrote:

on Tiddlywiki.com edit a tiddler and you will see a link to contribute to the docs.

This is new, isn't it? I already wanted to do that and I edited tiddler to see but I haven't see this nice explanation. This is great.

Of course you don't see it if you use the static version which seems to be the one given by google search unfortunately. Maybe the warning

at the top of static pages should bring to the right tiddler and explain the doc can be improved there.

[TonyM]

Yes

I have being keen to change the static template to link to the interactive wiki for my own wikisite.

Tony

[A Gloom]

 

Of course you don't see it if you use the static version which seems to be the one given by google search unfortunately. Maybe the warning

at the top of static pages should bring to the right tiddler and explain the doc can be improved there.

Google search can't link to individual tiddlers in a wiki, only if the wiki has static pages like TW com has-- one of the disadvantages of a on-line single file TW-- I don't know about a TW on-line using node.js.  And unfortunately the message at the top of the static pages has a link to the default tiddlers not the tiddler of the static page hosting the link (possibly because much of TW's features get disabled in static pages-- see the static page TableOfContents-- it has a TW table of contents that is not functional).

Just gave me an idea to have a tiddler link feature to my static pages viewer...