TiddlyWiki documentation - discussion
Simon Baird
Edgar Javison
- I've read Daniel's Wikiguides and found them very useful for newbies.
- Bob's could be for advanced users.
- Simon's FAQs would be for those who want quick answers.
--
Edgar Javison
We are each of us angels with only one wing, and we can only fly by embracing one another. ~ Luciano de Crescenzo
Bob McElrath
> A while ago there was a bit of a thread on the direction that TiddlyWiki
> documentation should take. I will sum up:
>
> Everyone agrees we should have some and that a collaborative effort would be
> a good way to get things moving.
>
> There was a debate over whether the docs should be kept in a TW.
I'm very surprised to see non-TW even suggested.
> Keep it in a TW?
> Pros
> * eat your own dog food
> * Easy to write examples
It's the only way to write examples, and writing examples is *required*
for this. People will want to hit "view" and figure out how a given
thing is laid out. Doing toat on trac or MediaWiki will seriously
confuse users.
> Cons
> * Less support for collaboration (though ZiddlyWiki proposed as solution)
> * Have to download the entire content before you can read the faq. This is
> not good for directing people to a single FAQ answer for example
These are both good points, and fixing them have much wider applications
than just this one doc server/file.
On-demand loading has been suggested several times for ZW, and I have
recently implemented some things in that direction. Now when you log
in, ZW will download any private tiddlers that you didn't have access to
when not logged in. In addition the "revisions" tab uses on-demand
loading to grab old versions of tiddlers. (these features are in svn
but not released yet) I have even been thinking of the capability to
download an individual tiddler, which might even come from a different
ZW. This would enable us to embed *all* documentation into *every* TW,
so that it could be navigated by users without reloading their TW or
loading a new one. (which as the message box tells me, takes several
seconds! ;) For instance a single tiddler can be downloaded with AJAX
with a URL like this:
http://doc.tiddlywiki.org/?action=get&id=TiddlyDoc
or this to grab plain text with HTTP (but you don't get the
modifier/created/modified or revision info):
http://doc.tiddlywiki.org/tiddlers/TiddlyDoc
One might envision a definition of sites, so that a tiddly link to
Doc:TiddlyDoc will look somewhere for the definition of the server
"Doc", and then request the item "TiddlyDoc" from that server. Such a
wiki link syntax is commonly known on other wikis as an InterWikiLink or
RemoteWikiLink.
This proposal will run up against cross-site scripting security
protections, which we need to think about... (Though, from TW's
perspective this is easy to make safe since we're just grabbing data and
can choose to not execute systemConfig tiddlers downloaded this way)
If we desire a "light-weight" version of TW, we should think about ways
to do that. I think the best is to separate the js from the core.
Doesn't make it any smaller but might make it faster for repeat visitors
due to caching. The content of most wiki pales in comparison to the
size of the javascript.
Jeremy requested doc.tiddlywiki.org, so now I throw it to the community
to create. I suggest we import all the nice existing documentation
below, and someone put some effort into organizing it nicely. (Any
volunteers?) If you want to work on this you can create a login by
going here:
http://ziddlywiki.com/cookie_auth/signup?came_from=http://doc.tiddlywiki.com
> Around that time Daniel created http://tiddlywikiguides.org. Recently Bob
> unveiled this: http://doc.tiddlywiki.org which is a ZiddlyWiki site
> presumably intended to house all TiddlyWiki documentation. Also I have been
> trying to gradually build up some FAQs at http://twfaq.tiddlyspot.com/.
--
Cheers,
Bob McElrath [Univ. of California at Davis, Department of Physics]
Somewhere, something incredible is waiting to be known. - Carl Sagan
Saq Imtiaz
End-users dont need to see information regarding the TW core code etc, but for new TW developers such a resource would be very beneficial indeed.
Cheers,
Saq
Daniel Baird
That's true, but that just means there's two major headings in the one
table of contents, I reckon (or whatever the equivalent of a ToC is in
the doc format). Users become developers over time; we don't want to
go out of our way to hide stuff from "proto-"developers.
;D
--
Daniel Baird
http://tiddlyspot.com (free, effortless TiddlyWiki hosting)
http://danielbaird.com (TiddlyW;nks! :: Whiteboard Koala :: Blog ::
Things That Suck)
coolcold
collaboration. I dont see how downloading the entire content would be a
problem though given the content would likely be less than 500kB (rough
guess), which is small. As usual, on-demand loading is good and it
might already be implemented by the time it reached that kind of size.
I won't support the media wiki option because it would result in 2 set
of different wiki formatting.
Jeremy Ruston
> weaknesses at the moment
I'd agree, of course, although I'd also note that a good percentage of
the questions that crop up here in the groups *are* actually answered
in the existing documentation on tw.com. So I worry that even
'complete' documentation wouldn't deal with all our support
problems...
> b. state my opinion that TW may not be the best tool
> for the TW docs
I'd prefer that we did use TW because of the point that Bob makes
about keeping simple examples, and because it enables us to distribute
documentatin via TW - in particular, the right place for at least a
core of the docs is in tw.com itself.
> c. a call out to TW users with some spare time and some writing ability to
> contribute to the documentation
Definitely interested in volunteers to help with writing, and really
would like to find someone who can be an overall editor for the
effort; as well as individuals prepared to do the writing, we need
someone who can shape the overall work by maintaining the large scale
structure and establishing a 'voice' for the documentation.
> d. request some clear directions (Jeremy?) so that those TW users can pull
> in the same direction
Let's pull together at http://docs.tiddlywiki.org/.
Cheers
Jeremy
--
Jeremy Ruston
mailto:jer...@osmosoft.com
http://www.tiddlywiki.com
Chris Lawley
On 15 Sep 2006, Daniel Baird wrote:
> That's true, but that just means there's two major headings in the one
> table of contents, I reckon (or whatever the equivalent of a ToC is in
> the doc format).
(assuming here you mean a split between beginner titles and advanced
titles)
Not necessarily - and I've not thought this through completely, but
there's plenty of scope in TW to allow for 'advanced' information to
be hidden via a menu option - a tick box or some such.
It does, however make the text harder to write since you'll need to
spell things out for a beginner which generally means writing things
twice
- "See Spot run, run, Spot, run"
- "The mechanics of getting a robot dog to run entail..."
Maybe the option should hide the _beginner_ stuff
_OR_
Borrow from the text books, keep everything visible and make the
advanced stuff accessible from the beginner's text via links.
At the same time ensure there's a decent index and consistent
tagging
You shouldn't rely on the search -- you can't search for what you
don't know is there -- hence the good index (= Tiddler list with X-
ref tiddlers)
Then you need a couple of people to act as overall Editor (2 because
you gotta sleep sometime ;)
_Then_ you need a friendly newbie to read through it and say where
it's all nonsense!
Overall consistency is key...
... as are several other things, but that sorts out a lot of
headaches for the reader.
chris @:-|
(in the midst of a major hard drive crash and corrupt b/u :(
Chris Lawley
On 15 Sep 2006, Jeremy Ruston wrote:
> I'd agree, of course, although I'd also note that a good percentage of
> the questions that crop up here in the groups *are* actually answered
> in the existing documentation on tw.com. So I worry that even
> 'complete' documentation wouldn't deal with all our support
> problems...
Ah, gentle author, you have discovered the bane of all documentation
- the intended audience.
If it weren't for them, life would be lovely. We used to say 'the
only good user is a dead user'
<grin>
In my experience, the _only_ way to get the average user to read the
documentation is if there's a really good hook.
Either it has to be _fun_ to read (not really possible in this
adventure)
or it has to be _really_ _really_ easy to find the question/details
that match what the user is wanting to solve - and I don't think
anyone has managed to do that; it's always so much easier to ask
someone who knows...
Given TW's complexity maybe there could also be a series of question
tiddlers to lead the enquirer past the irrelevant, but fascinating,
deviations to the answer. Kinda like one of those old adventure
books.
chris :-)
Chris Lawley
On 15 Sep 2006, Jeremy Ruston wrote:
> Definitely interested in volunteers to help with writing,
[FX: Raises hand]
Got some skills in this area
> Let's pull together at http://docs.tiddlywiki.org/.
Come on, come on
Let's pull together
(Now now people)
...
- Canned Heat
Erm 404?
Or am I just too darn early
chris :-)
Simon Baird
> Let's pull together at http://docs.tiddlywiki.org/.
Come on, come on
Let's pull together
(Now now people)
...
- Canned Heat
Erm 404?
Or am I just too darn early
chris :-)
Ok, stop pulling there. Stop!
Now pull here:
http://doc.tiddlywiki.org/.
That's better...
I can't help adding my two cents:
1. The markup used for writing the docs is not relevant to the user reading the docs. That's crazy. The user just wants to read the stuff. (And be able to access it logically) Granted it's a little more convenient to the author. Eg, writing example formatting or using another markup. But example formatting is going to make up a fairly small percent of the docs.
2. Bob's suggestions for how ZW might someday be able to display a quick FAQ without loading the entire TW are nice but right now there are off-the-shelf, proven, tools that do a better job. No offense to ZW developers but other tools are more mature and more capable.
3. An important thing for Documentation is structure. What is the suggested method for structuring the docs at TiddlyDoc?
Another random suggestion.. how about putting the docs in a docs section of the trac wiki?
--
Simon Baird <simon...@gmail.com>
Jeremy Ruston
> 1 & 2
For me, the primary motivation for using TW as the basis for the
documentation is so that we can distribute the documentation as part
of TiddlyWiki. It seems unarguable; we ought to be able to write a
single tiddler describing, say, bulleted lists and then make it
available via the web, and as an intrinsic part of vertical editions
of TW that choose to incorporate documentation.
> 3. An important thing for Documentation is structure. What is the suggested method for structuring the docs at TiddlyDoc?
There's a basic structure embodied in the tags that are there now, but
I'd imagine that at this point we'd benefit from some discussion about
the best taxonomies to use.
> Another random suggestion.. how about putting the docs in a docs section of
> the trac wiki?
See above; doing so would preclude distributing the same documentation
as part of TW.
It may be that you're thinking of highly tutorial material which
doesn't need to be distributed with TW, which may be the case, but I'd
argue that our number 1 problem is that we don't have a clear,
complete, well organised repository for basic reference documentation.
google....@dfgh.net
1. The markup used for writing the docs is not relevant to the user reading the docs. That's crazy. The user just wants to read the stuff. (And be able to access it logically) Granted it's a little more convenient to the author. Eg, writing example formatting or using another markup. But example formatting is going to make up a fairly small percent of the docs.
convenience for author would mean either more people involved or less time spent in writting the same doc. Example is another thing which can be easily created, comparitively. This is mostly useful for the advance users of course, to give example plugins, which could be difficult, if at all possible, to do in non-TW medium
2. Bob's suggestions for how ZW might someday be able to display a quick FAQ without loading the entire TW are nice but right now there are off-the-shelf, proven, tools that do a better job. No offense to ZW developers but other tools are more mature and more capable.
I agree partially. It will have to be judge based on the timeframe when load-on-demand would be complete. However, I believe 500kB to 1MB doc size is acceptable. Will need some guess work as to whether it would be completed by that time.
Another random suggestion.. how about putting the docs in a docs section of the trac wiki?
I second this.
Just my 2 cent
Ken Girard
bulleted lists and then make it available via the web,"
prettylinks to have a backup external link if the tiddler didn't exist.
[[Bulletpoints|Bulletpoints|http://www.tiddlywiki.com/#BulletPoints]] A
shadow tiddler in TW that listed all the standard formating/macros as
prettylinks which could then point to the appropriate tiddler in TWs
offical document site (Once we get one).
As to making a tutorial that is fun take a look at
http://poignantguide.net/ruby/ [Why's (Poignant) Guide to Ruby]
But while a tutorial of this nature might keep me reading when I first
am learning about TW I think we also need a site that is answering
questions about some of the major plugins and how they work together.
With functioning demos. Somewhere I can go and ask things like "How do
I get forEach to write a toggleTag?", "How do I combine reminders and
forEach", "How do I write a different tiddler's title in this tiddler?"
etc. This makes it a place a person like me (Not a newbie, not a guru)
can turn to for quick answers/reminders of how this and that work.
And I am willing to help write stuff (After September), and am a decent
proof reader (even if I can't spell... spelling is what Word is for).
Ken Girard
djp
I'm an enthusiastic end-user of TW, but I don't care to learn HTML and
CSS just to tweak it one more notch beyond its present capabilities. If
anything, I'd like to trim-off some of the bells and whistles to make
it more compatible with low-end browsers like those in mobile phones
and PDAs. (Oops, that moves me over toward the developer side, doesn't
it?)
What about separate docs for simple users, reluctant developers (like
me) who rarely want to tweak anything, and enthusiastic developers who
want to understand and control all phases of TW?
Saq Imtiaz wrote:
> Slightly off-topic perhaps, but it might be a good idea to have a bit of a
> division between end-user documentation, and developer documentation.
>
> End-users don't need to see information regarding the TW core code etc, but
quoclinh
which is what we want to achieve:
1. TiddlyWiki Introduction
2. TiddlyWiki basics
3. Quick start-up
4. FAQs (basic question and answer)
5. Knowledge Base
a. Issues and resolution
7. Quick reference
8. TiddlyWiki available plugins
9. TiddlyWiki adaptations
10. Current known issues (bug tracking)
and more...
These have to be broken down into section in the left menu bar and go
from there.
For FAQ and KB, we can have a tool using FormTemplate or Eric's form
and html rendering to enter and automatically format the documents.
Best regards,
Quoc Linh
zayphod
for my work since I started playing with these tools about a month ago.
Good documentation was lacking, but I found a lot of answers to my
questions by spending a lot of time searching the discussion groups.
A few weeks into development, I had an idea to port one of my projects.
However, I had already forgotten some of the things I had already
learned. Also, I was asked to do a workshop showing how to use
TiddlyWiki for faculty. So, I decided to catalog the tricks and codes
I was learning about. I began a set of Notes on using TiddlyWiki. The
natural thing to do was to build a TiddlyWiki documenting everything.
This is somewhat along the lines being discussed, but aimed at the
novice.
I am not sure how useful it would be to others in this large community,
but feel free to look at what I am doing. It still needs more work -
rearrangements, correct crediting, etc. It is based on things I found
myself doing as I developed sites for my classes and an online journal.
The current Notes are posted at
http://people.uncw.edu/hermanr/Wiki/WikiNotes.html and my other posted
TiddlyWikis are linked from the page
http://people.uncw.edu/hermanr/wikilist.htm
This might give some ideas as to what to do, or not do, when creating
documentation. Any input would be appreciated. I still need to reread
these postings to see what I may be missing.
Thanks for your time,
Russ Herman
ccahua
I logged in to http://doc.tiddlywiki.org/ to add my 2 cents to the
tiddlywikipedia experiment and found it a fun experience to actually
contribute to a community wiki when previously I've only used TW as a
standalone!
I really like the feature in TW 2.1beta with the TW feeds in the
ImportTiddlers plugin.
Perhaps as more people pull together at this repository they can import
their tiddlers like Russ TW notes at http://doc.tiddlywiki.org/. That
way when 2.1 http://doc.tiddlywiki.org/ will be one of the feeds that
users can selectively import the tips they want depending on their
level and interests.
In my day job, I'm familiar with ontologies (snomed, umls etc) and the
like and from experience nothing is ever set in stone, but an initial
centralized effort helps consolidate critical mass toward adoption.
Hopefully http://doc.tiddlywiki.org/ will be one of those major
repositories so users can benefit from not having to search around.
Other ideas:
TW history/museum: timeline of TW milestones
TW cool sties, developer roll call - a list of plugin authors or tweaky
cool contributors
I'm still waiting for an O'Reilly title :-)
Heck you can drop in some ads in to help support TW community
endeavors.
Best,
tony
ps Happy belated birthday TiddlyWiki and thanks again to all the
developers, enthusiastic end-user-reluctant developers :-) and users
who help make this wonderful tool
MorrisGray
documentation.
I think the less verbose the better, using Ockham's Razor, if it can be
said with a bullet point then don't use a paragraph. In addition if it
can be said with a bullet point it is better said with a number point
since communications in answering any questions is more clear using
numbers than little round balls.
Also using an old salesman's adage, "Find out what the user wants and
make it easy for them to get it" To this end I don't think asking the
user to edit a tiddler to find out how the formatting is done is the
user friendly way. The example should be obvious at first glance.
I have put up a 'Linking in TiddlyWiki' on http://doc.tiddlywiki.org/
as a humble illustration of what I am trying to say. I wonder if any
one agrees?
Morris
Nick
It has solved many years of trying to find ways of organising myself
and my projects.
My first reaction to this topic was that something like MediaWiki was
needed. But now I realise that would be self-defeating! I agree with
the "Ockham's Razor" approach. TiddlyWiki already has (with all our
contributors expertise) the tools to organise an effective
documentation project with the use of tags and all those great plug-ins
now available.
Primarily, we should use TiddlyWiki as the delivery method as it is
then proof positive of it's capacities!
That leaves the difficulty of online collaboration to achieve our
outcomes? I think this has been discussed before here or elsewhere. Do
we need to use a Server-side version to achieve collaboration? I think
yes! But here I am slack in not having checked earlier comments on such
a suggestion.
I can only say, that if a Server side option is chosen, i would vote
for ccTiddlywiki. It is the solution I have chosen elsewhere and it
can, at any point, create a standalone TiddlyWiki for those that want
one.
(P.S. Just started using Google Toolbar spellchecker for these posts
and we need to get them to update their dictionary for "TiddlyWiki").
Sharon
Chris Lawley wrote:
> In my experience, the _only_ way to get the average user to read the
> documentation is if there's a really good hook.
> or it has to be _really_ _really_ easy to find the question/details
> that match what the user is wanting to solve -
As a general user, this is somewhat true. I have spent hours and hours
in documentation trying to find the answer to some basic question (not
necessarily in TW). Time is of the essence, and a quick answer on a
forum so much easier. A great search engine does wonders for
documentation.
Sharon
sraasch
myself organized. I have found that one of the things that slows me
down the most when it comes to understanding something in a project
like this is TERMINOLOGY. While I truely believe that I can either find
or ask for the help that I need, understanding the information that I
get requires that I understand the terms that are in common use within
the community.
Unfortunately, people in the community already understand those terms,
while I may not.
With that said: how about a glossary of terms to put us all "on the
same page"?
"Thanks for your support"
-Steve
Saq Imtiaz
With that said: how about a glossary of terms to put us all "on the
same page"?
A glossary explaining terms like tiddlers, tags, plugins, shadow tiddlers.... should be one of the very first links in the MainMenu !
Great idea.
Saq
DaveG
and it has been interesting...
I am giving a paper in October at PhUSE in Dublin in October about TW,
and there I have said it is the only viable widely available tool that
can deliver comprehensive documentation and simple nubie hints *at the
same time*.
You can do this with tagging and by constructing front pages for your
different audiences, this will get easier in 2.1 when we can have
customisable next/previous links.
There are big advantages to having it all in one, in particular you can
leave tag trails so users can go deeper exactly on the bit they need,
without having to access a separate document.
And with tagging you can give people ways to navigate that you didn't
even think of.
DaveG