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:
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:
- 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.
- 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.
- 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.
- That's a docs "bug". TWikiDocumentation is a bunch of INCLUDES of individual topics, so the TOC goes to the first instance of
Overviewevery 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
- 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.
- 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.
- 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.
- 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.
- 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
Editand checking the raw text page source. Like WebIndex and WebChanges. Also, the docs aren't exactly without examples, just not necessarily demonstrated. In TWikiVariables, underTOPICLIST, there are three ready-to-go examples, like:
%TOPICLIST{" "}% creates an option list (for drop down menus)So go:<form> <select> % TOPICLIST{" <option>$name"}% </select> </form>and you get a pull-down list: