create new tag
, view all tags
I find the documentation for Twiki hard to read. I do not know much about the twiki community so I have not expected context for this tool. The manual is written more as a programmer reference manual then an introduction. It would greatly help me if the Overview section of each chapter contained some "Use Cases" for me to develop context. I would like the manual to speak more of the language of the users of the system and less of the language of the people who wrote the code. I do not think this would take much effort, but since I am having trouble with the manual I can not offer to help.

Why would a user use this feature (skins, templates)? What purpose would the user be trying to accompish?

This could be either "goal oriented" discribing a general goal OR using a specific simple example use (use twiki as a "bug tracking system").

-- KenEstes - 13 Dec 2001

Hey, Ken. You're right about the amount of effort required, if you're referring to properly updating the manual. But I think, if you're willing, you COULD help. Having a problem with the manual is, like, a prerequisite. And since you ARE fully qualified, would you like to help?

Just steady feedback would be great.

I'm a non-corporate, non-programmer T/Wiki convert and fanatic, and I volunteered for docs for about the reasons you mentoned. At one point last August - major new features had been coming on quite furiously from mid-March 2001, to the 01-Sep release - I got confused for the first time by some new/improved feature that I didn't get right away (maybe the double pass templating system). I volunteered 'cause I felt that docs were suddenly key to keeping TWiki from sliding into TOO specialized territory. TWiki targets the "corporate intranet market", where it seems that those who implement it have programming or related info systems knowledge.

So perhaps part of reason for the dev notes nature of the docs is the target user/contributor. Many TWiki installations have to be kept private for R&D/company security. And a lot of cool examples, templates, etc, from a broader user base, probably wouldn't interest, or be of direct use, to the core Codev group here.

Especially with high-end corporate users, I get the feeling that there may be a whole bunch of heavily customized TWiki installatons that're practically their own versions of TWiki, that we don't see or hear about. Could be wrong.

Anyhow, here or three specifics that could help the docs, with the first one kinda underway:

  1. Total rewrite/refactor the User's Guide - This is the first set of topics on the TWiki web main page. Many of the articles overlap in content, and they're all in different writing formats. Maybe the choice of style works for some, but fewer and covering everything once probably works best for most.
  2. MORE tech/programming-lite explanations - this may sound weird, but, before filling up the docs with with examples, I could see more "friendly tech" content. Explanations for technically unfazed non-programmers, about how things work. For example, with, say, WebNotify, explain not just how to set it, and how the programming works - "triggered by cron job setting, whatever script/routine checks meta data for whatever field,...blah, etc...." Odd? Maybe. But it somehow fits with Wiki-ness. It's like...organic. More people think in terms of processes these days, understand better that way, too.
  3. MORE custom configuration examples: a docs page appendice, or even a third section, as a dedicated installer/admin cookboook, with tips, cut'n'paste code, etc. Even full template webs, with forms, topic templates, even design and GRAPHICS, customized for various specific applications.

Any input you have - what bothers you where - would be great!

-- MikeMannix - 15 Dec 2001

Here is a list of gripes about the current documentation.

*) When using the main index at the top of the TWikiDocumentation page, all the Overview links take you to the same place. I would like to be able to read the overviews for each section.

  • That's a docs "bug". TWikiDocumentation is a bunch of INCLUDES of individual topics, so the TOC goes to the first instance of Overview every time. Pretty annoying - I've never really used the all-in-one version. Will figure something out.

  • Mike: I experimented a little with adding hidden text "markers" to the overview heading in TWikiInstallationGuide -- it didn't help. Then I simply appended "_2" to the overview section (making the heading "Overview_2") and that did work. (Sort of ugly, but, not knowing when a real fix may occur, it is a workaround.) Sorry I don't have more time today. If no one has a better suggestion, I will change all of the Overview headings to include numbers, sometime after the new year. Aside: Tried the hidden text within <> and within HTML comment markers <!-- -->, neither worked, possibly because I left a space after the word Overview -- I'll experiment with that some more when I get a chance. -- RandyKramer - 27 Dec 2001
    • Randy: Oh, I saw that and left a question. I thought that might be it. I wouldn't bother redoing all of 'em, though - there's bound to be an easier solution that isn't confusing. The quickest is to remove all the Overview headings - slightly less friendly TOC, but it'll only take a minute for users to realize there's an overview right under every main section heading. But maybe Peter has a fix, since this is at least an almost-bug, since it would affect other common heads, like Known Issues... Thanks once again!! -- MikeMannix - 28 Dec 2001

*) reassure me that I can press 'stop' on my browser at any time and this will not cause bad things to happen to Twiki. Inparticular I worry about RCS locks/partial updates/repated reloads of post data/etc.

  • Consider yourself reassured. As far as stopping dead wherever you are, you're fine up to your last save and nothing weird will happen. There are sub-issues, like RCS records only the last version by a user within the preset lock period (IOW, every save isn't automatically another version). And there's a little cache problem with IE 5-6, where, in some situations, if you go back from Preview and don't see your changes, you have to go forward again and save. Normal quirky stuff :g:. But as far as, say, your machine/network crashing in the middle of something, you're fine to your last save.

*) I often work in a paranoid corporate setting. 'User Authentication' issues that I would like specific instructions on how to do would be:

1) lock the twiki so that only the admin can add new users. I anticipate that getting this deployed in a large company might be difficult BUT it may be easy to get a small enough group to use this. The group would need to assure corporate that only they can change their documentation.

  • If you're using basic authentication, you can easily restrict the registration script. Etc. This sounds like a general Web/intranet security issue, not TWiki specific - restricting access to any software or files. Look through this - Codev - web for relevant comments and people to talk to. There are apparently a number of large scale - hundreds of users, thousands of changes/month - mission critical deployments. Like at TWiki founder/lead dev PeterThoeny's own company.

2) Remove all access for a Twiki user who leaves the company. In particular I was a bit freaked out when I saw the Twiki development staff automatically got accounts on my new Twiki Installation.

  • Heh-heh. I found a TWiki site where I was registered. I thought that stuff was removed, or there's a note about how a few accounts are in the distributed package for some packaging reason and should be removed. I don't know why this is necessary/most convenient in packaging. Earlier versions had even the WEBMASTER preset. Some of it is just labor - clean-up time for the distrib. I'll check. It's not good - it can really alarm people. The rest, removing access, is normal online security stuff, as in my previous comment.

3) I believe that user groups can contain other groups as members. This is a badly needed access control paradigm. It would also be useful to be able to look at the complete list of all group members (transitive closure) so that unexpected interactions can be seen. I image there should be a way of getting the groups members printed on a twiki page.

  • Post this as a separate dev question. I'm sure you can at least do a quick in context list of users in a group quite easily with a custom search, but someone else can answer this quicker and more easily than me thinking about it.

*) The more complex Predefined Variable have example usage. I do not have enough background to understand the examples. I will need some more context to understand how to use:

 % SEARCH {"text" ...} %

 % WEBLIST {"format"} %

 % TOPICLIST {"format"} %

 % TOC {"SomeTopic" ...} %

  • This stuff looks like "extras", but it's all quite "elegantly simple", variations on search used to create much of the cool basic TWiki functionality. Actually, the easiest thing to do is look at working examples on TWiki pages by hitting Edit and checking the raw text page source. Like WebIndex and WebChanges. Also, the docs aren't exactly without examples, just not necessarily demonstrated. In TWikiVariables, under TOPICLIST, there are three ready-to-go examples, like:

%TOPICLIST{" "}% creates an option list (for drop down menus)

So go:

     % TOPICLIST{" <option>$name"}%
and you get a pull-down list:

And FormattedSearch actually has demoed examples. Of course, the point is, more of these would be useful. It's just, who the program/docs primarily aimed at now, what do they need, and who's available to go beyond that. All mentioned (and agreed with by me) in my previous post above.

*) Twiki Forms. Forms is such a loaded word. When I think of forms I think of the CGI/Perl scripts which I write quite a bit of, however twiki forms do not collect structured data and pass it to an arbitrary script for processing. What are these forms? I am not sure but I think that they are a way of creating a small amount of structure (searching) to the otherwise flat Twiki "set of pages" model. I believe there is no other structure other then having different webs. So a Form is a well defined list of variables each one of which has a restricted set of possible values. Any twiki page include a form and will then have a set of variable/value pairs associated with it. Other pages may now display 'all pages which use Form A and for which variable B is equal to C. Is this close to correct? What are the restrictions? Queries are certainly not SQL so it would be nice to easily see what is possible. What happens if a form changes and there are many pages which use the old form?

  • Yes, that's basically it! The whole world of Wikis is about freeform text pages, searchable mainly by unique titles. TWiki greatly extends this search functionality with TWikiMetaData, all of the structured name/value pair info attached to each topic (and all explained). This includes user-definables, as in WebForms, and also data defining page attachments, rename/moves, etc. To look at it in probably the WORST (Wiki) way, the main TWiki freeform area - the Edit text box - is just one main special field among a bunch of other fields in a...database. Taken to an extreme, this almost kills the Wiki concept - if you structured most of your TWiki around complex sets of WebForms, searches, and metasearchs, it could end up as basically a text database. The assumption is that you use Wikis - TWiki - for collaboration in an open Wiki style first...but that idea can conceivably get lost with an abundance of extra features. Maybe I'm out of my (practical, as in, time and place) depth with MasterRefactor, but TWiki is so flexible now that it kinda needs a meta definition, for some, at least, which is the point of that. Is TWiki more of a Wiki Dev Toolkit, as opposed to an (advanced), standalone WikiClone? Does it matter?

*) File attachments and document versions. Please explain the interactions between these two different ideas? What if I need to rev the attachment and not the document? What if I need to rev the document but not the attachment. I believe that there are a few different usages for this feature which may effect how one uses it.

1)GIF, JPG and PNG images can be attached to add new graphics to a web

2) files like MS Doc, Power Point presentations, Drawings, might need to be version controled and shared while a group works on the binary documents.

  • If you're referring specifically to revision control in attachments, which I assume is working fine - as opposed to revision control of topic content - I believe it's all straightforward RCS, recording the changes between two versions, even if the the changes are the entire file (ie: you replace file). If you're using TWiki attachments as a simple document management (distribution) system, with various people uploading and downloading any sort of file (gif, doc, whatever), and then working locally with their own revision control (like, internal Word RC, or just a local independent RC system, or keeping incremental backup copies), it's up to you to decide how to work all that out. You don't have to use the TWiki attachment RC. To use TWiki as version control for external docs, you can't currently lock attachments (topics get locked when someone is editing), so a manual check in/out system - leave a comment - is necessary. It's all in that fuzzy area of where freeform Wiki ends and typical structured database/form models begin... If by _document you mean the main topic data, well, that's entirely separate from attachments, by definition, as it were - Wiki and Wiki extras._

*) I do not understand the section on 'How Rename/move Works'. I would need a bit of explanation about and its limits. An example move and all the issues which arise would be great here.

  • I just re-read/rearranged ManagingTopics. It's not all that different - not rewritten - but it makes sense to me. I'm not clear on your confusion...

-- KenEstes - 18 Dec 2001 <== This is my signature, Don't take it

All of the above are my answers based on use and doing docs. I'm sure additional developer comments, if necessary, will pop up! This is kind of an odd set of questions - almost trolling-style for me, based on a lot of comments I've placed around Codev. It's interesting, though, that since 03-Dec, I've been using/observing TWiki in a music/video production company intranet setting, where T/Wiki in theory is a perfect solution, but in practice, is not UNSUITABLE, but definitely needs a lot of the basics, partially mentioned above, and, in Codev, mainly in the "needed for buy-in" comments: templates, and the like. I'll reread my answers above and see if they fit directly in any way in the docs as they are now - a lot of it was thinking aloud about my own live TWiki situation. Is great software an independent property, or is it only great to those who can actually use it?

Please post back if this was helpful, or not, and why!!!!

-- MikeMannix - 27 Dec 2001

WillNorris, you suggested I can help with this stuff. Please let me know how best to proceed?

I think the general problem that has been and to some extent still is giving me problems is the vast amount of stuff that can be set and customized. Several problems exist:

  • How to find the information on how to do what I want to accomplish? For example, as an admin and/or user I really only know what I want to do. I should not have to know how variables, etc. are used to know how to change font size or style.
  • More examples, at least one showing how to set every variable that can be set. Currently, customizing things requires being able to understand how the code works just to know how to set most variables.
  • More sophisticated search functionality, possibly using meta-tags.
  • Good documentation on the *.css and *.tmpl stuff - including the ability to search that stuff. No need to be able to edit from the web interface, but would be good for an admin to be able to search both the TWiki pages and the code when figuring out how things work.
The general problem is that the documentation is written for people who already know a lot about the system, not for people who are new. (A horribly common problem when engineers write documentation!)

BrendonWhateley - 30 Sep 2004

How about slicing the documentation in different ways? For example,

  1. Index of % tokens
  2. Index of all topics that talk about authentication and protections
  3. Index of all topics that discuss formatting
  4. etc.

Alternatively, I have a 3/4 written full-content index plugin. It only works on words, not phrases, but it at least does the "index" piece of Microsoft Help. I'd be happy to donate it, or if someone wants to sponsor me, to finish it.

-- CrawfordCurrie - 01 Oct 2004

Edit | Attach | Watch | Print version | History: r15 < r14 < r13 < r12 < r11 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r15 - 2006-04-29 - SamHasler
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.