Beginners help for Table of Contents

[S. S.]

When I first found TiddlyWiki at the end of 2016, I was quite frustrated at the difficulty of finding beginner level instructions.

I've seen a lot of discussion about this issue in TW's Google Group.

During the recent posts on GG : Why is there no table of content in the empty wiki? - TiddlyWiki Google Groups - 2018-11-03 by bimlas ... this update of the ToC help tiddler was a quick result: Pull Request 3518 - github - 2018-11-07 by Mark S.

I felt it was time to attempt to perhaps contribute in some small way to filling in some gaps.

I worked on a Table of Contents for Beginners which is a blend of Stephen Kimmel's How to create a Sidebar Table of Contents tutorial and the Mark S.'s pull request shown above, and my own additions.

This compelled me to also attempt a Tiddlers for Beginners , Sidebar & Tabs.

Before I continue, I would appreciate some guidance and opinions if this kind of long-winded "very basic step by step style" can be useful on tiddlywiki.com and if so, then any corrections/suggestions to incorporate.

Table of Contents for Beginners

[aged...@yandex.com]

@S. S.

I found this to be extremely helpful.  Thank you for sharing!  It certainly would have cut my learning curve down by a very large margin. 

I have been getting so overwhelmed and bogged down with *how* to do what I want in TW5, instead of just being able to do what I want that I have seriously been considering trying other options. 

Step-by-step tutorials like this one can go along way in cutting the TW5 learning curve for those like myself who are not so technically inclined. 

Thank you!

[Mohammad Rahmani]

This wiki by S.S. is a great manual of slef-learning Tiddlywiki for beginners.

S.S has explained TW features beyond the besics (WIkitexts). It worth to get attention of all users and developrs.

I hope people in the forum have a look and give their comments for improving this wiki.

Some suggestion:

• Ask David Gifford to add this wiki to Tiddlywiki Toolmap
• Add to sidebar few tabs as below
• Basics
• Lists and filters
• Scripting in TW

It is important to have a sequential and step by step learning TOC. Nonlinear behavior of TW is not good for learning it.

--Mohammad

[S. S.]

Although this TiddlyWiki Docs group is not so active, I will still leave trails here for documentation issues.

I have been working slowly on the Beginner's level documentation, and lately I have been trying to sort out a small issue.

Should we call it "Beginners" or "Introduction" or anything else?

How I have named the tiddlers	Maybe better naming
Tags for Beginners	An Introduction to Tags
Fields for Beginners	An Introduction to Fields
WikiText for Beginners	An Introduction to WikiText
Widgets for Beginners	An Introduction to Widgets
Macros for Beginners	An Introduction to Macros

I have the suspicion that using "Beginners" is not the best idea. "Introduction" may be a better approach.
Also, starting each tiddler with -- An -- means they will be near the top of any alphabetically (default) sorted search result.

Feedback is not just welcome, but much needed.

What's been done so far: Documentation - Work in Progress
 Only about 25% of the work done is displayed when opened.
The Recent tab will give a clue as to what else is being worked on.

[thro...@yahoo.com]

Yeah, "Beginner" sounds a bit off-putting. Maybe one of those O'Reilly type titles like:

Getting Started With TiddlyWiki

Learning TiddlyWiki

TiddlyWiki the Easy Way

TiddlyWiki the Fun Way

TiddlyWiki made Easy

TiddlyWiki Unplugged

Bootstrap TiddlyWiki

Diving in to TiddlyWiki

Feet Last TiddlyWiki

Secrets of the TiddlyWiki Masters

Finding your way with TiddlyWiki

Exploring TiddlyWiki

TiddlyWiki for Fun and Non-profit

My First TiddlyWiki Guide

TiddlyWiki from the Start

-- Mark

[Rizwan Ishak]

I back the "Getting started with" idea. Docs already has a general getting started tiddler. Now specific getting started tiddlers for various topics.

Adding An ain't necessary, IMO. Whether people search for "Introduction to" or "Getting started with", tiddlers with those in title will show up.

Sincerely,
Dr. Rizwan Ishak

[Jeremy Ruston]

Hi SS

Just on the question of titling documentation tiddlers, I try to observe some advice I once read about "microcopy" and make sure that the important word is at the start of the title. The idea is that when scanning a list it is much easier for the brain to pick out the right title if they are distinguishable by their initial letters.

Best wishes

Jeremy.

--

Jeremy Ruston

jer...@jermolene.com

https://jermolene.com

--
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.]

Mark, thanks for the inspiration!

Here is a list that seems to keep with the spirit of Learning:

• A Guide to TiddlyWiki
• An Introduction to TiddlyWiki
• Exploring TiddlyWiki
• Getting Started with TiddlyWiki
• Learning about TiddlyWiki
• Starting TiddlyWiki
• Understanding TiddlyWiki

In all the above, each topic tiddler's name can take the place of "TiddlyWiki" - example: A Guide to Tags
The first two - "A Guide" and "An Introduction" - show up near the top of search results.

On the other hand, taking Jeremy's advice we could turn it around to:

• Tags - A Guide
• Fields - An Introduction
• WikiText - Get Started
• Widgets - Learning TiddlyWiki
• Macros - Understand TiddlyWiki
• Lists - Help
  

Search doesn't search the caption field or use it in the results displayed. We don't have a "key-word" field that can show up towards the top of Search Results.
Example, a search for any one of these terms: tags wikitext list field widget macro : give too many results to be quickly useful.
Thus finding the introduction level tiddlers easily when a lot of tiddlers are returned in an alpha sorted list, is an issue that needs consideration.

At present, these tiddlers have the main word from the suggestions above in their title:

Guide
"TiddlyWiki guide FR" by Sylvain Naudin
A Gentle Guide to TiddlyWiki
Documentation Style Guide
HelloThumbnail - Gentle Guide
WebServer Guides

Introduction
HelloThumbnail - Introduction Video
Introduction to filter notation
Introduction to Lists
Introduction Video
Introduction Video Thumbnail.jpg

Getting Started
Getting Started Video
GettingStarted
GettingStarted - Android
GettingStarted - Chrome
GettingStarted - Firefox
GettingStarted - Internet Explorer
GettingStarted - iOS
GettingStarted - Node.js
GettingStarted - Online
GettingStarted - Safari

Help
HelloThumbnail - HelpingTiddlyWiki
HelpCommand
HelpingTiddlyWiki

Learning
Learning

Exploring & Starting & Understanding
(none)

Thanks for the help!

[S. S.]

After not so much careful thought, I'll toy around with these two naming styles:

• An Introduction to WikiText
• WikiText - an Introduction

[Anthony Muscio]

S S 

Thanks for your contribution here, We need people like you pushing this documentation.

Can I also suggest we try and build solutions that help beginners, not just documentation but use a design approach. If you look at my site http://tiddlywiki.psat.com.au/ you will see a number of custom tabs in the side bar. My point is they are implemented with a single tiddler and that tiddler title is in the tab as a link. This means you can just drag and drop TableOfContents or Recent System tiddlers to you wiki and it will be installed. For some this will be a WikiText learning opportunity, for others it will simply be getting a TOC working, or a special tab.

The point is beginners tend to want results before understanding, but we have a habit of implying they should understand something first. I expect this may turn away the less computer literate amongst us. The Doc'o is critical but so to is access to the solutions. If we could aim to always provide accessible solutions at the front of documentation, not just examples at the end I think we will hasten the adoption process. People can always look at the solutions documentation when they come to want to customise theirs.

Regards

Tony

[S. S.]

Tony,

I waited half a day before replying because I wanted to think about what you said, because you are so right - many need a quick example to get them going - and thus holding their interest - and I mulled how to incorporate this into what I was doing.

After some careful thought, I think we will have to put that in at some stage.

Examples are not my forte. Explaining to new users how to move around, terminology, concepts, structure, things like those is something I can work on. Even just those may take creating, modifying and linking together maybe more than 50 tiddlers as they are so interconnected.

I believe a new user needs to quickly get familiar with terms used, otherwise the majority of the documentation leaves them confused, as it did for me when I first started. Simple things like, what is meant by a Widget, what is WikiText, What is a Story River - these are terms one gets to understand only after quite a few months of using TiddlyWiki.

I feel that having a resource to speed up that process will allow new users - who feel that TiddlyWiki appears to be what they want - to not get overwhelmed when trying to use the tremendous amount of material already available on the website that is in more terse, advanced forms.


It's much more fun to "code" and help give solutions to solve direct programming questions than to write documentation! Even I prefer reading and sometimes giving a creative solution in TiddlyWiki Google Groups rather than spending time on this documentation. So I understand why getting group collaboration on this simple topic of beginner's documentation is such a painfully slow process.

If I try too much, I may end up overwhelmed and inordinately delayed. Thus I want to concentrate on finishing this set before considering incorporating the next step.

It's  easy to see how far I have reached, and by clicking quickly through the ToC links, which parts are not yet done - here: Beginner's Documentation

Regards

[Anthony Muscio]

SS

Your doco is looking good. It is important we all work to out strengths, so lets all do that to start, then build new ones as needed. No need to start with a need to change.

I understand what you are saying about "It's much more fun to "code" and help give solutions to solve direct programming questions than to write documentation!" but I think this is only true because of the cognitive load it takes to transform piece on useful info into the documentation. I would happily jump from a solutions request or problem raised, check the existing doco and add a bit to fill a gap if I could but this simple transition is not possible.

Have you seen the complexity of the documentation features added to TiddlyWiki.com .macros and conventions you should follow with not template to make it easy? It has caused me to grumble "I am not going down that rabbit hole" for a voluntary effort when I need to earn a wage.

Regards

Tony

[S. S.]

When I first encountered the Documentation Macros tiddler which leads to standardizing the way documentation is presented, I too was quite taken aback!

Then as I started writing more and more documentation, I realized its necessity and value, and that it actually was not that hard to use.
I did however find those Doc Macros confusing enough for quite a while. So I decided to re-write that tiddler to :

• make it clearer for newcomer documentation writers
• make it easier to maintain that tiddler
• make some additions and tweaks (including to the actual doc-macros definitions & doc-styles CSS tiddlers).

I am 90% done, and this is a work in progress with the bottom 2 parts as yet incomplete. Its present state is here: Not yet complete Documentation Macros re-write.

On Wednesday, January 23, 2019 at 10:45:45 AM UTC+7, Anthony Muscio wrote:

...

...

[Anthony Muscio]

S S ,

Nice work, do keep at it.

Tony

[barro...@gmail.com]

SS,

If you can use anything from what I made for user instructions for the TW's I customize for people, please free free to use in full or part-- what may help you.

http://pyewackit.net/scratchingpad/guide/TWguidedocs.html#%3FF0%20Guide%20tabs

On Friday, November 16, 2018 at 2:43:45 AM UTC-5, S. S. wrote:

[S. S.]

It appears it falls onto me to make a decision on how to name the series, and we will just have to live with the consequences.

When I started writing this documentation, I felt it was for non-programmers. Along the way, I slowly swayed over to the belief that it would be better if it was for those who has some experience coding. Then the post by Birthe last week put things back into perspective (and made me laugh):

I do not understand why you find "Beginners" off putting. No matter who you are and what you know, if you haven't used Tiddlywiki before, you are new to Tiddlywiki = beginner.

I know absolutely nothing about programming. I have used Tiddlywiki for many years now mostly because I had a very good teacher (Måns). Tiddlywiki is so wonderful, it should really be for everyone, but people like myself need all the help they can get. (Beginners Guide). The difference will be the time they use going through your guide, at least I think.

Do you know people never reading manuals? They are often the people who think they know it all.....think it is sooo easy, nothing to it. You can not write a Guide for them.

Beginner can be a friendly and welcoming word to new users, as in this is also for you, no expectations of programming skills.

Note: Bold formatting above added by me.

It also reminded me of Jeremy saying somewhere:

TiddlyWiki wasn't put together and designed for developers. Software developers are already incredibly well catered for by the open source world. This program explores how the non-developer can be empowered.

So I have gone back to the basic reason I started writing this series, and will name it:

TiddlyWiki for Beginners

The next step is to present the instructions for those writing Beginner level documentation.
Those proposed instructions are reproduced in the next post and available here: Instruction Tiddlers for Beginners

[S. S.]

Below are the proposed instructions for those writing Beginner level documentation.
They can be seen in a TiddlyWiki here: Instruction Tiddlers for Beginners

---

The directions for writing Instruction Tiddlers for Beginners level material are in many ways similar to the directions given for writing general Instruction Tiddlers.

The main differences are that Beginner 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
  

Keeping this in mind, the information and instructions given is written in an informal style that constantly refers to the reader and should:

• use small steps, explaining each procedure in full detail
• preferably links in the text should be to other Beginner Level tiddlers if available
• specify the location of items being referred to such as:
• top right side
• bottom center
• lower left
• Ensure the location for narrow width devices is mentioned if it is different
• use a style that talks directly to the reader:
• "you can see"
• "your tiddler"
• "click the ... icon"
  

If links to more advanced tiddlers are given, these should preferably be:

• in the form of a revealable section under a "Show More Information on ..." button
• at the end of the tiddler (or if necessary at the end of a section)
• where appropriate, at the bottom of tiddlers there should be
• a link towards the "Next" suggested tiddler to read and a "Back" link to go back a step
• This should correspond to the order in the list field of the Beginners' Table of Contents tiddler
• If possible, a "Previous" link to go back a step (for tiddlers opened out of order)

To keep navigation easier for wide width devices, Beginners material will be presented in a toc-tabbed-internal-nav Table of Contents. Narrow width devices will have to click on "Next" or "Previous" links, or similar.

The rest of these guidelines are at Instruction Tiddlers.

[barro...@gmail.com]

 I do follow your guidelines somewhat

A recent general Intro/How To tiddler that i have start up (default tiddler) with a recent custom TW I made for someone

GENERAL DESCRIPTION & INSTRUCTIONS OF SOFTWARE:

• TO HELP VISUALIZE THE WIKI SOFTWARE LAYOUT:   If you look at this software as a website home page that will always display, while all its different content can be selectively shown and hidden as sub-pages of the home page.   Content sub-pages are called tiddlers in this software.   In the rest of this page and in the help files, they will be referred to as "tiddlers".

The basic layout of and names used in this software

• The left side is called the story river since tiddlers (content sub-pages), like this tiddler, will open on that side in a "story sequence" from top to bottom in the order you open them.   This will be your viewing and editing area.   Clickig on a tab will display its contents.
• The right side is called the sidebar.   The different tabs are different tables of contents.   This will be your menus and navigating areas.
  • The More & Tools tabs can be ignored for now– they are for wiki tools and functions and will be covered later.
  • The Open tab shows what tiddlers are open in the right side .   Recent tab shows recently created and modified tiddlers.
  • Click on a tab to open it to display its contents below the tab.   In each tab will be a listing of tiddlers titles.   Each tiddler in that list is a link to open that tiddler in the left side/story river.

For more info about the wiki layout and how to use it, see the HELP PAGES tab.

• The "?F0 Guide Index" will show general info about the software, its layout, some of its features and precautions.
• The "?F1 Help Index" will explain how to use the software and precautions.

[barro...@gmail.com]

A mistake  I noticed after the fact

• The left side is called the story river since tiddlers (content sub-pages), like this tiddler, will open on that side in a "story sequence" from top to bottom in the order you open them.   This will be your viewing and editing area.   Clickig on a tab will display its contents *(move down to next section).
• The right side is called the sidebar.   The different tabs are different tables of contents.   This will be your menus and navigating areas.  Clicking on a tab will display its contents.

• • The More & Tools tabs can be ignored for now– they are for wiki tools and functions and will be covered later.
  • The Open tab shows what tiddlers are open in the right side .   Recent tab shows recently created and modified tiddlers.
  • Click on a tab to open it to display its contents below the tab.   In each tab will be a listing of tiddlers titles.   Each tiddler in that list is a link to open that tiddler in the left side/story river.

[S. S.]

Thanks Barro!

I finally made the formal Beginners Documentation proposal on TiddlyWiki Github yesterday: https://github.com/Jermolene/TiddlyWiki5/issues/3926

Cheers

[A Gloom]

excellent! you had put alot of hard work into it and I've been paying
attention to see what I could use to improve my own work : )

unfortunately I haven't had the time to contribute here : ( why the
belated postings