My apologies for being quiet on this thread so far. It’s mainly due to being insanely busy with day job work, punctuated by a bad cold. Thank you to everyone for taking the trouble to contribute. I’ve read all the messages with great interest. It’s wonderful that there are so many people who feel passionately about the issue, and are prepared to help, and frustrating that we’ve been less than stellar at harnessing that energy.
First, I agree strongly with the consensus that: * The existing documentation isn’t serving the needs of our users * The update cycle for content changes to tiddlywiki.com is unacceptably slow * GitHub presents a huge psychological burden for would-be contributors * Google Groups is pretty poor I have always believed that my own primary focus should be on building and maintaining the authoritative core reference documentation. As discussed in this thread, such documentation cannot meet the needs of all users, but it is an essential bedrock on which all other documentation needs to be based. Beyond that reference material, we need multiple different tutorials to meet the needs of different users. The most useful material should be on tiddlywiki.com (such as the material that Dave contributed), and the rest should be easy to find from there. Related, we also sorely lack a convenient place to share snippets of TW wikitext. Beyond that, I generally think: a) TiddlyWiki is both powerful and complex: by any reasonable dimensions, it is several orders of magnitude more complex than something like Workflowy. With that level of complexity, for many users, just learning the vocabulary that enables them to use documentation is a huge barrier — in fact, even if we had great, complete documentation, I believe that we would find that many users still wouldn’t read it (that is a common experience for other projects). As Josiah has highlighted, just getting saving to work is a barrier for many users. Even if we reduce the number of clicks, the process is conceptually too far away from familiar paradigms to be intuitive for most users. The solution is simple: switch to using TiddlyWiki in a server-based configuration, but you lose the offline capability. That’s the trade-off: conventional usability vs. the ability to do something that no mainstream web application can support b) GitHub isn’t the only barrier to contributing documentation on tiddlywiki.com. It may not look like it, but a lot of effort over the years has been taken by several people to try to standardise the formatting and presentation. For example, there are a bunch of macros and templates that thread together the filter documentation. There’s a level of complexity to those macros that will never be intuitive to a casual user, but are needed in order to help us maintain consistency c) Ultimately and ideally, we should base TiddlyWiki documentation efforts on TiddlyWiki itself d) I struggle with the expectation that the documentation can or should directly address a question like "How do you append to a list a title with spaces using a text reference”. It’s both complex and specific, and it lacks enough information for a definitive answer (I loved Mark’s response about buying a book on first aid and complaining that there's no chapter on removing kidneys). Anyhow, responding to that question involves several different mechanisms, and thus would be very hard to anticipate as something to be answered directly in the documentation. Put another way, I see TiddlyWiki as being made up of a relatively small number of parts that can be combined in lots of different ways. It’s reasonable for us to document those parts exhaustively, but we will never be able to directly document every way in which they can be combined I’d also add a few clarifications: * The current TWederation work by Jed, Mat and others is primarily focussed on peer-to-peer federation. That’s a fundamentally tricky thing. Like TiddlyWiki saving itself in the browser, it goes beyond what browsers are designed to do. But it works, and opens up some fascinating use cases. Meanwhile, we can also do federation on the server under Node.js, where the technical difficulties melt away. That’s how the threaded discussion on http://tiddlywiki.com/tiddlywiki-eu-meetup-2016/ was built; the result is a simple HTML file that downloads swiftly. * Riz mentions the problem that off-the-shelf JavaScripts are hard to integrate with TiddlyWiki. Again that’s a trade-off; partly related to security, but also architectural concerns: TW5 could have stuck with the 10-year old jQuery style architecture, or it could have adopted the newer virtual DOM style architecture that’s now been adopted by Angular, React and all the other leading web frameworks of the last few years — many of them have the same difficulties with integrating older-style scripts. TW5’s choices mean that we get serverside rendering which I think is generally worth it. I should also mention that it’s pretty easy for a developer to integrate non-DOM-oriented 3rd party libraries. There are nearly a dozen 3rd party libraries already packaged as plugins in the core library, and many more elsewhere. * To answer another question posed by Riz, I don’t think that the Tiddlyverse is at all averse to the idea of setting up an organized community documentation. * Mark asks whether the stuff currently in TiddlyWiki now technically copyrighted, or can it be ported to another working environment. This is a good example of something that should be crystal clear from the existing documentation: all of TiddlyWiki's documentation is made available under the same BSD license as the code. I’ve no idea what the copyright position is on the Google Group posts, mind you. Thinking about some specific proposals from this thread: * I’m not averse to evaluating Discourse as an interim solution. I’m not sure whether it would be better to replace or augment the existing Google Group * I do not favour adopting MediaWiki, mainly because TW’s wiki syntax is confusing enough without burdening authors with an additional syntax (people will long memories will recall that tiddlywiki.org was based on mediawiki in 2008/9) Please let me know if I’ve missed any points in the thread, Best wishes Jeremy > On 6 Dec 2016, at 20:00, 'Mark S.' via TiddlyWiki > <[email protected]> wrote: > > If that's what you want, just submit a write-up to Jeremy/github about any > new sites you find, and encourage others to do the same. There's already a > short list at tiddlywiki.com/Community/Examples > <http://tiddlywiki.com/Community/Examples>. > > We could have a sticky thread (Gallery) in this forum nominating sites as > they are discovered, and whoever wants to could do the github submission. > > Mark > > On Tuesday, December 6, 2016 at 11:27:09 AM UTC-8, Josiah wrote: > Ciao Jed, Mark S. & tutti > > Seeing FULL WORKING TIDDLYWIKIS that exemplify different aspects of what TW > can do is, in my case, the single biggest HELP. > > I am not good with "in principle" minimalist demos or "foo-bar" stuff. That's > my cognitive limitation, I think, and its a bit more extreme than normal. > Though maybe not a million miles away from some beginner's experiences. > > I have learnt the MOST from FULL CONTENT TW's that do things I need to do. In > these cases I can grasp the underlying code much more easily BECAUSE I can > see SUBSTANTIVE OUTPUT. > > IMO, a simple GALLERY of extant full TW's solving different issues would > help. Of course there are ALREADY pointers to exemplars within the core > documentation. And well as galleries that exist, but really not on TW5 and > not up to date. > > Its just a fact that many of the most exiciting TW's I will never get to see > because their authors are creating them (a) offline; (b) or if online then > not specifically identified or linked to to look at. You have to catch them > as you go along reading the Goggle Group when they come up in discussion. > > In fact we don't even really know what exists. TW does not track anything. > > This is NOT a complaint. It's an observation. But it has some bearing on > documentation. Why? > > Because seeing finished, functional, replete TW's is likely one of the MOST > important routes to understanding USE CASES. It certainly is for me. > > SO ... perhaps PART of concerns about documentation could be encouragement of > more people to upload their TW's so that people can look at them. IMO that > might solve a LOT of issues to do with HOW to use TW for DIFFERENT purposes > (i.e. USE CASES). > > Best wishes > Josiah > > > On Tuesday, 6 December 2016 10:26:36 UTC+1, Jed Carty wrote: > Raymond, > > That is the idea behind having different editions. Unfortunately there aren't > many editions created or supported. So if you have something you want put > together a wiki for an edition and we can see about getting it listed. As far > as tiddlyfox goes, you generally get it from within the browser interface so > including it in a zip would be a bit weird. > > I made this a while ago to address what you are talking about but never > received any feedback about it so I haven't bothered with it in a long time. > http://nolearningrequired-full.tiddlyspot.com > <http://nolearningrequired-full.tiddlyspot.com/> > > -- > 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] > <mailto:[email protected]>. > To post to this group, send email to [email protected] > <mailto:[email protected]>. > Visit this group at https://groups.google.com/group/tiddlywiki > <https://groups.google.com/group/tiddlywiki>. > To view this discussion on the web visit > https://groups.google.com/d/msgid/tiddlywiki/4fbe425d-1fbe-4b09-8154-7b439f9f3526%40googlegroups.com > > <https://groups.google.com/d/msgid/tiddlywiki/4fbe425d-1fbe-4b09-8154-7b439f9f3526%40googlegroups.com?utm_medium=email&utm_source=footer>. > For more options, visit https://groups.google.com/d/optout > <https://groups.google.com/d/optout>. -- 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/2DFD4EB6-4586-4AEE-83DF-42233A1D8A74%40gmail.com. For more options, visit https://groups.google.com/d/optout.
