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 
of documentation:

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 
work.

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 
helpful. Dave

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 ...
> Josiah
>

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to tiddlywiki@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywiki.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywiki/bbe17ea2-1a64-4718-928d-df1d97e770fe%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Reply via email to