David That is a really excellent, detailed, and IMO, very accurate, balanced, description of the situation.
You penultimate paragraph is absolutely spot on IMO. Very often, as a naive user, I follow the docs only to find out I missed something that is some kinda semi-documented something--but where the range of its application is very context dependent and where there seem to be no exact rules. Life is too short to test the 62 variants to find out what the rule actually is! Best wishes Josiah On Thursday, 1 December 2016 15:56:02 UTC+1, David Gifford wrote: > > 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, > and which I added 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/62053d1d-d0b4-47f6-bf05-8dbd497d0477%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
