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 [email protected]. To post to this group, send email to [email protected]. 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.
