Proposal for improving TW Documentation - Structure (part 1)

[moros...@gmail.com]

Hello,

I want to propose a new structure for the TiddlyWiki documentation. In my opinion, improving the documentation in every aspect will make TW not only more useful but a lot more popular and attractive. The general idea is a more formal (standardized) and concise documentation structure. I don't mean to offend anyone but to share my experience and maybe to save other from the frustrations and obstacles I've ran into in the process of learning TW. Don't get me wrong, I'm not near an TW expert I just consider that the quality of the documentation can be raised a bit to make it look more professional.

Proposed improvements

• Less confusing and more concise chapter titles. - e.g. "Basic Usage" instead of "Learning"
• Higher level of abstraction and specialization – maybe more hierarchical levels.
• Chapters (and their contents) should have a more natural (logical) and progressive order.
• A clear distinction between different types of documentation (e.g. guides vs. references) - guides will be mostly used by beginners and references by advanced users.
• Chapters should be discrete areas of interests with a specialized role – not every user have time to read all the docs before creating the simplest thing  - get things done now, read the concept behind them later (when there's time for this).
• The panel title should be "Docs" or "Help" not "Contents" (minor).

Proposed structure


GUIDES

• Welcome (a presentation similar to HelloThere)
• How to read the documentation

• Getting started
• What is TiddlyWiki
• Comparison with other wikis/knowledge management tools
• Choosing an edition
• ...

• Installation and basic configuration
• Downloading and installing
• Setting a backup routine
•     - ...

• Basic usage
• Site navigation
• Create and edit tiddlers
• Search tiddlers
• ...

• Advanced usage
• Creating and using macros
• Using built-in widgets
• ...

• Configuring and customize
• Changing site title and subtitle
• Setting a favicon
• ...

• Administration and maintenance
• Updating TiddlyWiki
• ...

• Extending and developing
• Creating and using plugins
• Creating and modifying themes
• Developing modules
• ...

• Seeking for help
• Known problems and limitations
• Post a question on a TidldyWiki Forum
• ...

• Helping the community
• How to report a bug
• How to contribute a fix/improvement
• ...

REFERENCES

• Concepts
• Examples
• Dictionary
• TiddlyWiki Editions
• External resources
• Forums
• Community resources
• Plugins
• Sites
• About

Thanks!

[TonyM]

Thanks for the Effort, I support your proposal.

I think the examples should include all basic features people may need to use, not just select examples to explain the technical. Links from the documents to examples should be common. Much of the detail is concise for someone who already knows how to do it, but a single tiddler may demand already understanding 5-10 concepts. This makes it really hard to digest it as a first time user. It is a rare case of needing more verbosity without dumbing down.  No concept should be without practical applications to see and view, this helps people who use learn by doing, to help them progress. Some of the great logic and design principals should be voiced rather than only found by induction after you gain an expert level of understanding.

I love TiddlyWiki and Version 5 but it is a steep learning curve to just do more than the surface level features.

Thanks
Tony

[moros...@gmail.com]

Hi Tony and thanks for your support/feedback!

I agree with you. There are many problems with the current documentation that are a source of confusion an frustration. I have planned to cover the problems with the content in the second part. In case my proposal will not be accepted, I will make an alternative documentation system on my site anyway to demonstrate my ideas.
But to have a really useful documentation and put things on the move we need to raise our voices. So I invite you and other interested people to share your opinion/proposals here and also on the GitHub issue dedicated page: https://github.com/Jermolene/TiddlyWiki5/issues/2912

Thanks
Adrian

[@TiddlyTweeter]

If you look back you will see on the main group a lot of discussion of how to arrive at better "documentation". I have been heavily involved in some of that. In the last few months there have been two major attempts to supplement documentation via Reddit & StackExchange. The first is stalled. The second goes on on, though slowly.

Its entirely obvious that whilst Google Groups is fine for ongoing discussion it is absolutely the worst for being able to find past things. Which is a shame as many answers needed are buried in its history.

FWIW, my own viewpoint has changed quite a lot from when I first wrote about the inadequacies of documentation--especially it poorness for newbies. NOW I think that the biggest issue is the FRAGMENTATION of knowledge about TW, NOT lack of documentation per se.

The main documentation page IS fairly minimalist because its largely just one person--Jeremy Ruston--writing it and I believe he wants to concentrate on fundamentals. Its not always, in all parts, user-friendly, but its better than nothing.

Also, partly all this is a consequence of what TW itself is. Considering how many people are using TW its remarkably difficult to get to see fully complete TiddlyWiki's. But that's because (1) a lot of them are off-line; and (2) what is on-line is not well indexed. Google searches don't bring many of them up (for a bunch of reasons, some of which could be improved upon, I think, to all our benefit).

IMO, you would likely be more effective either trying to bring what is known (& published somewhere) together, OR concentrate on one or two areas where you have skill and provide more in-depth tutorials & suchlike. I truly think you will find that trying to fix TW documentation, as a whole, solo will not work. In the short time I been here I have seen 5 or 6 failed attempts at that already.

So whilst I'm really in favour of what you are pushing for, I'm now more in favour of "joining-up-the-dots" --because I think it has a chance to work. I also think replete examples teach much, even in small numbers. As do in-depth tutorials. There is MUCH information around. Its just hard to find it.

So, possibly a modest aim would deliver a more sustainable result?

Just my two cents.

Very best wishes
Josiah

[moros...@gmail.com]

Hi Josiah and thanks a lot for your effort to give me a thorough answer.

I've waited an answer like that can offer me some kind of summary of the problem because, honestly, I didn't know how/where to find it and my searches didn't gave me satisfying results.
I don't want to be misunderstood. I didn't say that the content itself doesn't have value or utility. I'm just saying that the structure of the documentation can be improved to make things more easier to find. It's not an original idea, I've seen this kind of structure in other manuals/doc systems. My intention, at the moment, is not a complete overhaul, just some moving things around and maybe a little renaming of tiddlers. Reclassifying the content, not recreate it. IMHO it should make a great difference, because I don't see a clear and meaningful organization strategy in the current structure.
"There is MUCH information around. Its just hard to find it." I totally agree and that's exactly what makes the documentation not so useful, especially for beginners. One of the main purpose of a documentation should be to help users to find the right knowledge as quickly as possible or they will search somewhere else. It's a natural thing. My personal view (and experience) is that augmenting the current content is not gone resolve the biggest issues that make the knowledge "hard to find". And I think this is the main problem that we should fix in the first place. I will give you just one example: the installation procedure. It should be that far away into the 3rd chapter? And the search will not gone direct me to the source either because a tiddler with the name "Installing TiddlyWiki" doesn't exist. What is the purpose of knowledge if it is hard to find anyway? We are just feeding a monster that will eventually become to big to control, so we better act no My primary source of learning TW (and I thinks it should remain the primary source for everyone) was (is) indeed the official documentation but my overall impression is that it could have been an easier and more enjoyable ride.
I will try to make a demo to demonstrate my ideas first ("A picture makes a thousand words"). Maybe I'm wrong but I think it's worth a try first.

Adrian.

[TonyM]

Adrian et all,

There seems to me to be two issues, the structure of the documentation and the knowledge within it. There are great resources out there that document many details well, however they often suit a particular audience well, but rarely for the newby (if it does its over simple). If we can establish a suitable structure (perhaps multiples) and bring in content from the other resources, we can then have an ongoing conversation about the details. Adding a feature not unlike Wikipedia where a discussion can take place, versions and rollback are possible would then help.

Perhaps one of the experienced members can build a multi-contributor wiki on which we can structure the content. We could also indicate the source eg; tiddlyWiki.com so we can refer back and propose updates.

Just brainstorming

Tony

[@TiddlyTweeter]

Ciao Adrian, TonyM e tutti,

A footnote.

I think the approach can be developed empirically. What does a newbie need?

Talking for myself, back when I started, IF I had been pointed to a resource (that effectively stands in for training) like Ton Gerner's Customisation TW I would have saved a lot of time. Its got a clear PURPOSE that pretty quickly makes sense. IMO, beginners main issue with TW is around purposes, as Danielo has commented elsewhere: "What do I do with this thing?" And then the second question arises: "How do I do it?"

An alternative documentation approach might benefit from keeping those two points as strong organising principles?

Best wishes
Josiah

[moros...@gmail.com]

Ciao ragazzi,

In my proposal I'm not trying to cover only the newbies but all kind of users, including myself. That's why I proposed two main sections: GUIDES and REFERENCES. It happens to me very often to forget the exact syntax or parameters order of a macro, so I need some kind of quick reference that is very easy to access to just take a peak. The resource you've pointed out should be in REFERENCES section in a chapter called "External resources" that can function like an index with community best resources around to help you reach the next level but the essentials should be in the official doc (GUIDES). I don't know if my (or other's) alternative structure will be an all-in-one solution (this is not my purpose for now), but maybe it will make finding stuff a little easier. In my vision, first it should exists some kind of a "masterguide" (presentation) that describe briefly all the capabilities of the app and after that there should be guides that will cover every concept in detail with links to examples or other types of helper (community) resources. I like the idea of TonyM to create a wiki to which we all can contribute. Maybe on a free wiki hosting service? A new discussion have initiated on GitHub (https://github.com/Jermolene/TiddlyWiki5/issues/2927) so you and other can share your thoughts.

Regards
Adrian

[@TiddlyTweeter]

Ciao Adrian

moros...@gmail.com wrote:

It happens to me very often to forget the exact syntax or parameters order of a macro, so I need some kind of quick reference

On this I think you are absolutely, unequivocally, without doubt, right.

A series of Crib Sheets could be a Godsend.

Best wishes
Josiah 

[TonyM]

Of special note is TiddlyWiki enables multiple views and collection of the same content. We should be able to provide different structures that support different user populations or degree of knowledge. A standard tiddler with standard tabs with related tiddlers about each element we wish to document could also allow people to explore as deep as they need. 

To me the trick is to build a living document that we can contribute to, such that should I find a great use case I can quickly post it into the documentation, should someone see an alternate way, or an additional parameter is added.

Regards
Tony

[moros...@gmail.com]

@TonyM I don't know if I clearly understood what you said but maybe we have a similar perspective. I imagine a documentation system that's dynamic not static, with multiple views, capable to morph based on some user selected criteria. That means, the ability to find knowledge in multiple ways: parsing a standard progressive structure, selecting knowledge by tags or sort it by difficulty level, dependencies/requirements, intended results etc.but I guess this is a long term objective. So maybe it's wiser to start with just the basic (and feasible) improvements. In the beginning, my expectations are that a clearer and meaningful (logical) doc structure will more appealing for users that wish to contribute. Every doc page at it's right place so everybody will have a clear picture of what already exists and what's needed. But enough talking :), we should do something, to have a baseline and continue from that. I will try to go on TonyM path and looking for a free wiki hosting service and put my initial proposal there.   

[TonyM]

I can provide a free MediaWiki instance if you want, in a day or so, but my preference was someone to build such a thing in tiddlyWiki itself.

Just ask if you want the mediaWiki instance and provide a user name and email address (to AM [at] PSaT.com.au) if you want me to grant full update rights, otherwise I will allow moderated new user account requests.

To clarify, the same documentation repository can serve multiple users by providing alternate entry points,  a different index or lists into the content. I Would also see value in the Multi-tab tiddler Idea where each tab references an external tiddler, I will provide a mock up soon.

Regards
Tony

[TonyM]

This requires deeper thought, perhaps with different "tracks" Newby, User, Dev - but here is a quick one

• Overview should describe the feature and what id does in both simlple and advanced uses
• Context - the various contexts in which this feature fits and can be used eg actionWidgets
• Syntax simple and full
• Examples - various meeting most needs "out of the box", ideally complete not context dependent snipits
• Advanced usage - extended uses such as in macros/plugins, detailed info
• Community notes -User and Developer sections with a series of posts on this command inc snipits, on review may incorporate into other documentation tabs

[Arlen Beiler]

We could use Wikibooks as well if we wanted to. Plus they already are used to doing things in the book sort of way. I started a couple books there a few months ago, but I am not a writer. However I believe Wikibooks would work perfect if we want to use MediaWiki. We can also have our own project area to discuss things related to documentation.

--
You received this message because you are subscribed to the Google Groups "TiddlyWikiDev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywikidev+unsubscribe@googlegroups.com.
To post to this group, send email to tiddly...@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywikidev.
To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywikidev/62719adf-24fa-4023-b9b0-4ff9461f112e%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Arlen Beiler]

Toward that end, I updated the page with the list you posted in your original email. Here it is.

https://en.wikibooks.org/wiki/TiddlyWiki_for_Users

I have a feeling the reference might end up in a separate book.

We could call it the TiddlyWiki Desk Reference.

Someday, there will hopefully be an artfully and tastefully written TiddlyWiki for Dummies.

[moros...@gmail.com]

@TonyM a TiddlyWiki version was my idea initially but a I didn't want to put all my efforts in it without a minimum community support/help. On the other hand a TiiddlyWiki version would have all the obstacles/limitations that the current GitHub version has, that makes collaboration very difficult. Once we'll reach a certain agreed version I will try to make a TiddlyWiki version.
@Arlen I'm fine with using Wikibooks (though I never used it before) and thanks for creating the initial structure. If it's ok with others too (TonyM) we can continue from this point.

[moros...@gmail.com]

Hi to all,

I've already started using the Arlen project on Wikibooks (https://en.wikibooks.org/wiki/Wikibooks:WikiProject_TiddlyWiki) and even made some modifications. I invite you all there!

Adrian.

[moros...@gmail.com]

I also start developing the new "TiddlyWiki Manual" in my TiddlySpot wiki (http://morosanuae.tiddlyspot.com/#TiddlyWiki%20Manual)

[TonyM]

I am fine to move with the crowd. One reason I suggested tiddlywiki is because there is already a lot of great content, for example I have gained a lot from Tobibeer's https://tobibeer.github.io/tb5/#Welcome which has being helpful in this phase of my learning. The content is out there, just not in one place, and without curation and interlinking.