Ideas to improve incomplete documentation by incorporating community docs, reorganizing the current one

[bimlas]

In my opinion, the biggest drawback of TiddlyWiki is the lack of transparency in the documentation: the answer to each question may be written, but it is difficult to find it. Anyone who has just discovered Tiddly is unlikely to use the search engine first, but the table of contents, so it should be tidy. Jeremy also seems to be open to rewriting the docs (https://groups.google.com/d/msg/tiddlywiki/7xlxfZf72CA/_udld3tvCwAJ) and there was an attempt (I didn't read it all, but if someone has enough time, it can be instructive): https://github.com/Jermolene/TiddlyWiki5/issues/2912

What's the problem with the current docs, why can't we find what we're looking for?

Category names are unclear or not exactly what their names refer to. Which I think is a problem:

- Learning: What are you learning? You always learn when you recognize a new feature. The tiddlers are in bulk, Learning is more of an Advanced Usage and should be displayed later in the table of contents after Working with TiddlyWiki (which describes the basic usage).

- Features: There is Import Tiddlers and Info Panel, which I think rather belongs to Working with TiddlyWiki.

- Plugins: Why is there a separate documentation for creating plugins and the entire "technical" documentation itself at https://tiddlywiki.com/dev/? Why isn't this included in the official documentation?

- Reference: Basically good, but for example, Filters -> Filter Operators are bulk, not categorized (a possible solution is Locator plugin (https://bimlas.gitlab.io/tw5-locator/), see in attached wiki)

- Community -> Resources: Same as Reference

I think Learning, Working with TiddlyWiki, Customise TiddlyWiki and Features can go together, because there is no significant difference between them: for example, Working with TiddlyWiki has Keyboard Shortcuts, which fits to Customisation as well.

Tiddly's current docs should be categorized again, using clearer category names such as "Reading and navigating", "Writing", "Automatisation", etc which would be determined by the nature of the feature described. For example, using the tags would be part of the "Reading and navigating", but adding tags to the text should be under "Writing".

...

It would be good if we found an example of a good, easy-to-understand documentation of any software, but I haven't found that yet.

Based on my experience, most of the documentation prefers the table of contents as the main navigation, works like a printed book. This is basically good, because beginners can get a higher level of knowledge by going through it. When someone knows the program better and wants to look more in detail or more precisely, the table of contents and the search engine may not be enough. TiddlyWiki is flexible enough to make aggregated content lists by filters based on different functionalities: a good example is http://tobibeer.github.io/tb5/#Solutions. Since these two lists are incompatible, we could display them in separate sidebar tabs: a classical ToC (tab name could be "For beginners"), tiddlers grouped by functionality ("Advanced users" tab) and developer notes and referene ("Reference" tab).

...

Instead of writing long descriptions (TLDR: too long, didn't read), it would be enough to have a wizard, and some illustrative examples that show the operation in practice instead of having to read a lot: https://cdn.rawgit.com/abesamma/TW5-editions/78846468/empty.html ->Start Tutorial

More examples are mentioned here as an advantage as well: http://erwanm.github.io/tw-community-search/#CommunitySearchVersusOfficialDoc and Jeremy also agreed with writing several examples (https://groups.google.com/d/msg/tiddlywiki/7xlxfZf72CA/_udld3tvCwAJ).

To show the true power of Tiddly, we need similar descriptions to show that how the user has probably made notes so far and why Tiddly is better than that: https://joearms.github.io/#2019-01-08%20My%20Eureka%20Moment%20with%20the%20TiddlyWiki - it drives the user to interactivity, enters playfully into Tiddly's higher use.

In addition to "how to", it could also show us a use case of a feature (for example, SubStory may be useful and I understand how to implement it, but I can't imagine a situation when I need it: https://tiddlywiki.com/#Creating%20SubStories). Write expressive examples, for example https://tiddlywiki.com/#How%20to%20add%20a%20new%20tab%20to%20the%20sidebar could show a specific sidebar tiddler where the user can see what fields must be written.

...

There is a bunch of documentation scattered across the Internet, all of which complement the official documentation, yet difficult to find for a beginner:

- https://tiddlywiki.com/

- https://dynalist.io/d/zUP-nIWu2FFoXH-oM7L7d9DM

- http://erwanm.github.io/tw-community-search/

- https://www.reddit.com/r/TiddlyWiki5/wiki/index

- http://tobibeer.github.io/tb5/#Solutions

- https://kookma.github.io/TW-Scripts/

- https://00ss.github.io/help/Adding-a-table-of-contents-to-the-sidebar.html

As Jeremy also asks us to work on documentation (https://tiddlywiki.com/#HelpingTiddlyWiki), I think that all of this information should be written in the official wiki.

Merge all of this documentation into one place, to https://tiddlywiki.com/! To achieve this, more contributors would needed on GitHub who approve the merge of the docs (because Jeremy has no endless time), although the description seems to indicate that this is already the case: https://tiddlywiki.com/#Improving%20TiddlyWiki%20Documentation

Because everyone has a different idea of how to organize documents efficiently (someone prefers searching, someone uses the table of contents, tags, custom fields, etc.), I don't know how to find the gold middle which everyone agrees.

...

To avoid misunderstandings: I appreciate your work to invest time and effort in writing the missing documentation. All respect is yours! What I disagree with is just that you do this job not in one place, helping each other, but each one separately.

[bimlas]

Cavinton... Where's my Cavinton...? (-_-') Forgot to attach the example wiki...

[S. S.]

Thanks bimlas for taking an interest!

The present Table of Contents is actually an Index - listing just about every significant tiddler.

As a newcomer to TiddlyWiki, I actually almost never used it, because I could not figure out what I needed to read, and in what order. Nor was it practical to find anything there even if I had an idea where it might be. I still don't look at it for anything other than to see how it can be improved.

For an example of good, easy-to-understand documentation : https://www.w3schools.com/
I find that whole website set up and laid out in a way I can easily find what I want, find the way to do what I want, and find examples.

[S. S.]

bimlas,

Your idea of alternate separate sidebar tabs: a classical ToC (tab name could be "For beginners"), tiddlers grouped by functionality ("Advanced users" tab) and developer notes and referene ("Reference" tab) - is an interesing suggestion! It had never occurred to me to do it that way, and I believe it has merit.

I imagine my suggestion of having an alternate Table of Contents presentation for an Introduction to TiddlyWiki series on the website would fit this idea quite well.

[S. S.]

bimlas,

You touched on a point inferring that Jeremy reviewing contributions is a bottleneck. You are very right.

There is a good reason for this. I remember reading (or perhaps hearing in a talk) Jeremy mentioning words to the effect that TiddlyWiki has reached a point where the specifications in the documentation is the standard that the program has to maintain, as opposed to the program being the standard, and the documentation being in flux to keep up with the program. With this context in mind, it is essential that the documentation precisely defines what the program will and will not, can and cannot do. It is all too easy for someone who does not know the ins and outs of the program to use words that seem correct, but in fact contradict fundamental principals which are not obvious.

I don't know why I have this feeling, but I imagine Jeremy was influenced by this passage from : The Emperor's Old Clothes (1981) - by Tony Hoare where the writer is talking about an important software project that kept getting more and more delayed :

At last, there breezed into my office the most senior manager of all, a general manager of our parent company, Andrew St. Johnston. I was surprised that he had even heard of me. "You know what went wrong?" he shouted - he always shouted - "You let your programmers do things which you yourself do not understand."

I stared in astonishment. He was obviously out of touch with present day realities. How could one person ever understand the whole of a modern software product like the Elliott 503 Mark II software system?  

I realized later that he was absolutely right; he had diagnosed the true cause of the problem and he had planted the seed of its later solution.

It is necessary for at least one person to know EVERYTHING about the software - and we are fortunate that this is the case with TiddlyWiki.

Also this is what Jeremy recently wrote on a Github Pull Request Improving Developer Documentation #3339

I've learned the hard way that everything requires at least the level of review that I would give it myself. Even trivial seeming documentation updates can break established documentation conventions.

I myself have experienced this once, where I was convinced I had it down perfectly, and later realized how shallow my understanding was.

Cheers

[S. S.]

bimlas,

You have rightly pointed out that a few regulars are working on improving documentation. To quote :

is just that you do this job not in one place, helping each other, but each one separately.

The difficulty I have found is that there is often little feedback to what each person is doing. Almost no comments such as:

• I like the structure - go for it.
• That structure may cause these problems ... 1) .... 2) ..... 3) ......
• I think THAT name is better than THIS one
• You forgot to mention these 3 important concepts ...
• I think a learner should know about THIS widget before they know about THAT one.
• I don't like your layout, why don't you consider this one ...
• I think your explanations are too complicated : too simple

If there is feeble feedback, there can be no agreement to cooperate. Initial constant feedback is a form of stating an intention to continue participating. It takes time for an agreement to be made for all to participate. There need to be proposals and amendments, rejections, acceptance, and finally, a decision to - go for THIS EXACT structure & workflow. Of course it is not set in stone - but it gets everyone working and contributing towards the same goal.

But none of that happens when so few people say - YES or NO or CHANGE THIS or THAT IS MISSING

Here is a small attempt to give a STRUCTURE and GUIDELINES - 2 steps that need some agreement before implementation can be a group effort.

Structure: Introduction Level Documentation - What goes into it?
Guidelines: Instruction Tiddlers for Introduction Level Material

https://00ss.github.io/help/Adding-a-table-of-contents-to-the-sidebar.html

[Joe Armstrong]

On Sun, Feb 3, 2019 at 11:28 PM bimlas <bimba....@gmail.com> wrote:

In my opinion, the biggest drawback of TiddlyWiki is the lack of transparency in the documentation: the answer to each question may be written, but it is difficult to find it. Anyone who has just discovered Tiddly is unlikely to use the search engine first, but the table of contents, so it should be tidy. Jeremy also seems to be open to rewriting the docs (https://groups.google.com/d/msg/tiddlywiki/7xlxfZf72CA/_udld3tvCwAJ) and there was an attempt (I didn't read it all, but if someone has enough time, it can be instructive): https://github.com/Jermolene/TiddlyWiki5/issues/2912

What's the problem with the current docs, why can't we find what we're looking for?

Category names are unclear or not exactly what their names refer to. Which I think is a problem:

- Learning: What are you learning? You always learn when you recognize a new feature. The tiddlers are in bulk, Learning is more of an Advanced Usage and should be displayed later in the table of contents after Working with TiddlyWiki (which describes the basic usage).

- Features: There is Import Tiddlers and Info Panel, which I think rather belongs to Working with TiddlyWiki.

- Plugins: Why is there a separate documentation for creating plugins and the entire "technical" documentation itself at https://tiddlywiki.com/dev/? Why isn't this included in the official documentation?

- Reference: Basically good, but for example, Filters -> Filter Operators are bulk, not categorized (a possible solution is Locator plugin (https://bimlas.gitlab.io/tw5-locator/), see in attached wiki)

- Community -> Resources: Same as Reference

I think Learning, Working with TiddlyWiki, Customise TiddlyWiki and Features can go together, because there is no significant difference between them: for example, Working with TiddlyWiki has Keyboard Shortcuts, which fits to Customisation as well.

Tiddly's current docs should be categorized again, using clearer category names such as "Reading and navigating", "Writing", "Automatisation", etc which would be determined by the nature of the feature described. For example, using the tags would be part of the "Reading and navigating", but adding tags to the text should be under "Writing".

...

It would be good if we found an example of a good, easy-to-understand documentation of any software, but I haven't found that yet.

Based on my experience, most of the documentation prefers the table of contents as the main navigation, works like a printed book. This is basically good, because beginners can get a higher level of knowledge by going through it. When someone knows the program better and wants to look more in detail or more precisely, the table of contents and the search engine may not be enough. TiddlyWiki is flexible enough to make aggregated content lists by filters based on different functionalities: a good example is http://tobibeer.github.io/tb5/#Solutions. Since these two lists are incompatible, we could display them in separate sidebar tabs: a classical ToC (tab name could be "For beginners"), tiddlers grouped by functionality ("Advanced users" tab) and developer notes and referene ("Reference" tab).

The first rule of writing is know your audience - who is the documentation for?

 

...

Instead of writing long descriptions (TLDR: too long, didn't read), it would be enough to have a wizard, and some illustrative examples that show the operation in practice instead of having to read a lot: https://cdn.rawgit.com/abesamma/TW5-editions/78846468/empty.html ->Start Tutorial

More examples are mentioned here as an advantage as well: http://erwanm.github.io/tw-community-search/#CommunitySearchVersusOfficialDoc and Jeremy also agreed with writing several examples (https://groups.google.com/d/msg/tiddlywiki/7xlxfZf72CA/_udld3tvCwAJ).

To show the true power of Tiddly, we need similar descriptions to show that how the user has probably made notes so far and why Tiddly is better than that: https://joearms.github.io/#2019-01-08%20My%20Eureka%20Moment%20with%20the%20TiddlyWiki - it drives the user to interactivity, enters playfully into Tiddly's higher use.

What amazes me is how much can be done with so little - at a guess 95% of the fun can be had with 5% of

the features.

I am constantly reorganising things by changing tags and writing filters

<<list-links "[tag[a]!tag[b]]">>

So for me, my 5% is tags + list-links

For a beginner like me, I'm not quite sure what the 5% I should really learn is

The markdown bit seems obvious so I'll hop over that, but for other beginners, this might

be a big hurdle.

 

In addition to "how to", it could also show us a use case of a feature (for example, SubStory may be useful and I understand how to implement it, but I can't imagine a situation when I need it: https://tiddlywiki.com/#Creating%20SubStories).

I agree - I never understood what a sub-story was

 

Write expressive examples, for example https://tiddlywiki.com/#How%20to%20add%20a%20new%20tab%20to%20the%20sidebar could show a specific sidebar tiddler where the user can see what fields must be written.

Absolutely - In my experience, concrete examples are far easier to understand than abstract descriptions.

So one could say - I'm making a TW about my favourite films - so I wanted sidebar to reflect this - this

is what I did:

    1) I got rid of all the boring old buttons in the sidebar by doing this:

         <code>

    2) I added my own buttons "Oscars" "Actors" ... by doing this

        <code>

 

    Which looks like <click-here>

     And now we're ready to rock and-and-roll

...

There is a bunch of documentation scattered across the Internet, all of which complement the official documentation, yet difficult to find for a beginner:

- https://tiddlywiki.com/

- https://dynalist.io/d/zUP-nIWu2FFoXH-oM7L7d9DM

- http://erwanm.github.io/tw-community-search/

- https://www.reddit.com/r/TiddlyWiki5/wiki/index

- http://tobibeer.github.io/tb5/#Solutions

- https://kookma.github.io/TW-Scripts/

- https://00ss.github.io/help/Adding-a-table-of-contents-to-the-sidebar.html

As Jeremy also asks us to work on documentation (https://tiddlywiki.com/#HelpingTiddlyWiki), I think that all of this information should be written in the official wiki.

Merge all of this documentation into one place, to https://tiddlywiki.com/! To achieve this, more contributors would needed on GitHub who approve the merge of the docs (because Jeremy has no endless time), although the description seems to indicate that this is already the case: https://tiddlywiki.com/#Improving%20TiddlyWiki%20Documentation

Because everyone has a different idea of how to organize documents efficiently (someone prefers searching, someone uses the table of contents, tags, custom fields, etc.), I don't know how to find the gold middle which everyone agrees.

It might not exist - Ted Nelson says that all attempts to organise things into structures are doomed to

failure :-)

 

...

To avoid misunderstandings: I appreciate your work to invest time and effort in writing the missing documentation. All respect is yours! What I disagree with is just that you do this job not in one place, helping each other, but each one separately.

--
To post: TiddlyW...@googlegroups.com
To unsubscribe: TiddlyWikiDoc...@googlegroups.com
More info: http://groups.google.com/group/tiddlywikidocs?hl=en
Visit the wiki at: http://wiki.tiddlywiki.org
---
You received this message because you are subscribed to the Google Groups "TiddlyWikiDocs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywikidoc...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[S. S.]

Hello Joe,

Though bimlas is talking mostly about the general documentation layout on tiddlywiki.com in its present state, my interest for now is a new set of Introduction Level material.

This is how I have defined who I am writing this entry level documentation for.
The instructions to a writer (as proposed by me) for this Intro level of material is available in full here.

The directions for writing Instruction tiddlers for Introduction Level Material are in many ways similar to the directions given for writing general Instruction Tiddlers.

The main differences are that Intro Level tiddlers should assume that the person reading:

• is a new visitor to the site
• has no background information about any part of TiddlyWiki
• will not be familiar with common definitions and concepts of TiddlyWiki
• though being somewhat computer savvy, may or may not have some interest or experience in computer programming
• is looking for a clear, verbose presentation style
• needs to know what to read next
• is looking for easy, quick step by step solutions

[Joe Armstrong]

On Tue, Feb 5, 2019 at 1:15 PM S. S. <sachde...@gmail.com> wrote:

Hello Joe,

Though bimlas is talking mostly about the general documentation layout on tiddlywiki.com in its present state, my interest for now is a new set of Introduction Level material.

This is how I have defined who I am writing this entry level documentation for.
The instructions to a writer (as proposed by me) for this Intro level of material is available in full here.

The directions for writing Instruction tiddlers for Introduction Level Material are in many ways similar to the directions given for writing general Instruction Tiddlers.

The main differences are that Intro Level tiddlers should assume that the person reading:

• is a new visitor to the site
• has no background information about any part of TiddlyWiki
• will not be familiar with common definitions and concepts of TiddlyWiki
• though being somewhat computer savvy, may or may not have some interest or experience in computer programming
• is looking for a clear, verbose presentation style
• needs to know what to read next
• is looking for easy, quick step by step solutions

Great - I think one problem is imposing a linear reading order on the data in the TW.

I asked about how to build trails recently and I'd like to see more of these - the

"what to read next" problem is solved here.

TW's are very nice for *writing down your ideas* but present the reader with a problem.

We're all used to books with linear order for learning - as regards the TW I'd like

to see several 'trails' through the documentation targetted to different readers

Cheers

/Joe

 

On Tuesday, February 5, 2019 at 4:19:59 AM UTC+7, Joe Armstrong wrote:

The first rule of writing is know your audience - who is the documentation for?