Apologies for the long post that follows. I actually wrote most of this
earlier, to focus myself on the proper way forward for TiddlyWiki's
Documentation.
------------------------------
The thoughts below have come into focus while spending spare time reviewing
documentation for TiddlyWiki over the past couple of months.
I find I now need to step back and ask myself these questions about the
Beginner's level documentation instructions being written:
- Who is the target of these instructions?
- What technical level should be assumed of them?
- How can the present site be used to get the "right-target" new visitor
to start quickly and try out a few things?
- Not get stuck and frustrated and leave thinking this is not a fully
developed and documented program?
- How can I write instructions that allow readers to:
- become comfortable with the naming conventions
- get familiar with the underlying infrastructure and quirks of the
program
- quickly find and use the right tools the right way for their task
- gain insights for use in their own creations
To answer them, I realize I first have to try and understand exactly what
TiddlyWiki is and isn't. There are lots of serious, candid, and even comic
posts in Google Groups to give me clues, and I have tried to absorb them.
What I see as a "core" strength of TiddlyWiki is that it gives the
infrastructure and the tools to make "solutions".
As many programmers of integrated systems might quickly learn, there is no
- "one size fits all" - out of the box - "solution". There are just too
many scenarios and user's personal needs and desires to be taken into
account.
So, if my understanding is in the right direction, what goes into the
"core" of TiddlyWiki - should be either - "infrastructure" or "tools" - for
creating solutions.
I came to this understanding while looking at the Table of Content macros
when creating Documentation for Beginners. It has caused me to believe that
these macros are actually "plugin" material. In essence they are not
"platform" or "tools." I imagine similarly that, though I have never used
it, the whole Journal system is the same. They are both "user-solutions."
To change tack now, the first post in this thread
<https://groups.google.com/forum/?hl=en#%21topic/tiddlywiki/TbB9T36QSlA>
starts with looking at how other programs are "doing it" ; that inevitably
leads towards the notion of "Marketing" TiddlyWiki. As I have noticed, this
usually leads to creating "user-solutions."
Since most any part of TiddlyWiki can be "programmed" and customised, one
will have a limitless number of "solutions." It takes a lot of time,
effort, and testing, to make comprehensive - end user friendly "solutions."
Something as "seemingly" simple as the Table of Contents macros, that have
been in use for years, still have noticeable issues
<https://github.com/Jermolene/TiddlyWiki5/issues/3627>.
Thus, out of the necessity of keeping TiddlyWiki maintainable, it should
make sense that "ready-made end user-solutions" released in empty.html are
kept to the absolute minimum, else continuous tweaking (followed by
testing) to satisfy users' needs, may soon become unmanageable for the
development volunteers.
Now, back to the Documentation issue.
The user-base for TiddlyWiki's Documentation should perhaps not include the
vast majority - namely those who are unable (such as through lack of
skills, motivation, time) to set up and personalize it for their own ends.
Instead it should focus only on those who already have some basic
programming skills, and also the inclination, ability, and time, to use
TiddlyWiki to create solutions for themselves and others.
Helping those *who are able* to create personal or "end-user-solutions" on
their own - and who need insight from the knowledge base of regular users,
could be considered as a key target. Trying to create documentation that
entices those looking for "ready-made" solutions, but unable or unwilling
to "play the TiddlyWiki" game - seems pointless.
It may be wise to accept that actual creation of ready made solutions is a
branch separate from the venture of core TiddlyWiki.
It may then also be wise that Documentation should be written with the
purpose of luring this "right user-base", and structured so as to entrap
them into this fascinating TiddlyWorld we share.
--
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/c77198b1-ab2f-4107-83b6-35ba36202d9e%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
