I want to affirm Josiah and Riz's frustration, from someone who has done
introductory documentation for TW classic (TiddlyWiki for the rest of us)
and the current TiddlyWiki (which you can still find on tiddlywiki.com, via
Github, and Github was a miserable experience for me. I still don't get it).
Six things to try to explain (and defend, but not excuse) the current lack
One problem is really a blessing: there is seemingly a limitless amount of
things you can do with TiddlyWiki, and limitless ways to customize it. So
to imagine a documentation site that could cover all those possibilities
seems too great. The possibilities are so many that is even hard to know
how best to structure or organize a documentation site for TW, which I know
from experience. For example, Jeremy and I had very differing opinions at
one point because Jeremy prefers noun and definition-based categories for
documentation (this is what a macro *is*, and this is the machinery behind
it), whereas I prefer verb and illustration-based categories (this is what
a user wants to *do*, how can she do it?). As you can see, that distinction
alone would result in two very different ways of organizing the
documentation, like a car mechanic's manual vs a driver's manual.
Another problem is that TiddlyWiki is a moving target. Updates have slowed
down, but for a while the new versions were coming out every 2-4 weeks, and
doing documentation would require extensive monitoring and rewrites. Not
much of an incentive to do documentation.
Another problem is that many of the users are not writers and find it hard
to understand and communicate with less technically savvy end users like
me. Much of the documentation lacks use case examples, and after many of
the answers I have received here, I have had to ask them to explain it
another way because I didn't have a clue what they were saying. This is not
a criticism of the community, more of a defense of them - writing tutorials
or explanations would not be their gift or passion, so it is too much to
expect from them. Whereas they show time and time again that they will
generously help people when given questions that are stated specifically
and clearly enough. So the Google Groups format works.
Another issue is GitHub. Using what to me is a system with a very
complicated learning curve to document another complex system. Too much
Another issue is that development of TiddlyWiki goes in random spurts based
on the limited attention span of key players. Things that get mentioned on
Hangouts, in conversation, or in the GitHub issues list, at first are given
a lot of attention, but if something else that is interesting comes along,
the first item gets left hanging and even forgotten because the attention
is now on the second item. I remember when list fields were the big thing,
and I was confidently told there would be a UI for rearranging list items
with drag and drop, etc. Never happened. There was also discussion on a
hangout of doing a flexible table format where each cell is on a different
line and could be formatted. When I asked about it some time later, I was
told, "Why would anyone need that? Just use an html table" as if I was
talking about something out of the blue. Could multiply examples of what
almost sounded like promises of what would be in TW but that never
materialized. So I tend to now take things with a grain of salt.
Another issue is that the minute things stabilize, a web browser decides to
change things around completely. Now I am hearing that Tiddlyfox will not
work in an upcoming version of Firefox. Not only does this mean I have no
idea how I will use TW after that happens, but it requires fixes that then
require changes in the documentation.
On another fairly separate note, one thing that bugs me, not so much about
documentation as about learning TW, is that there are too many things that
are similar to each other that you really have to learn them well or create
cheatsheets to keep it straight. For example, widgets and macros. In some
cases they do the same thing but the syntax is different: <<list-links
filter:"[tagging[bob]]">> and <$list filter="[tagging[bob]]"/> What I don't
understand is why the one has : after the word filter and the other has =.
A little standardization there would have helped a lot. And the distinction
between [tags[ [tag[ tagging[ is not clear, and sometimes the syntax is
the opposite of what the function is. ([tagged[ would have been preferable
to [tagging[, I think) I turn to Tobias Beer's list filter reference page
often, and even then I struggle to combine lists within lists or add CSS to
one part of a list. And @@. @@ isn't always as flexible as <span class=""/>
so they are not synonymous ways of wrapping with CSS. (eg you can't put
@@.@@ inside of another @@. @@ as you can with spans). And for indenting
there is : and > and I think two other ways. Great that we have so many
options and so much flexibility! But it makes it difficult to conceive of
documentation when there are ten ways of doing each thing. And more to my
point, it is really hard to learn all this stuff when it all looks so
similar but really is not.
Anyway, this is not a rant. Just some comments on documentation and
learning to take into consideration. Hopefully someone will find them
On Wednesday, November 30, 2016 at 10:36:44 AM UTC-6, Josiah wrote:
> Ciao tutti
> In the last two weeks I've had extensive private correspondence with three
> folk over on Twitter who want to know where to find the "real
> documentation" for TiddlyWiki. After pointing to what documentation there
> is I suggested they ask in the group on specific things they want to do.
> If I hadn't engaged in that discussion with them I would never have know
> there are potential users who are likely passing on from not being able to
> grasp enough quickly enough to be able to utilise TW well.
> I think its a problem (for them at least) as is.
> Just saying ...
You received this message because you are subscribed to the Google Groups
To unsubscribe from this group and stop receiving emails from it, send an email
To post to this group, send email to email@example.com.
Visit this group at https://groups.google.com/group/tiddlywiki.
To view this discussion on the web visit
For more options, visit https://groups.google.com/d/optout.