TWiki Set-Up Troubles

This may be a shortlist of problems, but it actually just flips into a pretty simple To-Do list - with a lot of the work on the docs level - that, completed, wouild make a big differentce for non-tech development and all that.

• Earlier, I read through all of the success stories in the Main web, and the TWikiClones list of installed sites. There were some impressive stories from SAP, Motorola, other large companies, with bits of casual detail about whipping up a distributed TWiki, or fine-tuning tie-in to databases...hmmm. But no links, course. Of the 10 or so links I did follow - all happy TWiki-fied groups, for various companies, some with hundreds of people, even a juggler's association - they were ALL basically uncustomized, most with TWiki still in the corner, and the same web colors. A couple were changed a bit, but all were still pretty raw. And they all seemed to be used as straightforward text repositories: pages of stuff. Basic Wiki use, which made me realize, imagining that most TWikis should/could be like the high-end ones is unrealistic, unnecessary as well.

• Then, for the first time since Nov, I installed a new TWiki, the latest Beta, to use to work with a few people as an informal project tracking/notes/collaboration site. So, all I want is a clean, basic TWiki. And, while thinking about the mass of discussion about deployment lately, I spent 2-3 hours just changing web and standard feature names: web to zone for all the titles in the config file, some of the mentions in text. So it's ZonePreferences, ZoneStats, ChangesNotify, ToC for WebHome.
  • Web to Zone: very nice. I'm adopting this approach. -- MattWilkie

I also renamed Main and TWiki. It's still only partially done, and dull work. What I did was manual, could've s/r pages at a time, etc, but why people wouldn't bother changing much. I did create three more webs, and change the colors. That's it. Compared to installing, say, a BBS, with literally dozens of color selections, and text/icon changes, that can be manually done through a Web form in 20 minutes, I could be at this for hours! A Pref for changing the logo at least would be...nice.

Anyhow, a lot of this stuff is happening now, skins, etc, but really, until then, the core package is tough to deal with before even considering heavy customization and code tweaking issues. Just to get something "presentable" - in the same sense as the high-rez logos vs TWiki-bot logo, involves:

• manually changing colors, and having to change font colors as well to get any variety (only so many decent light colors)
• dig around in templates to change logo
• same for stylesheets to change font size and style
• and then, on the border for some, create basic forms and summary searches to go with them
• check out and install several plugins
• for me, back in templates, rearrange the toolbars, get rid of bits, add a back to top button and a clickable weblink on the bottom bar...

Getting all that out of the way - clearly indicating how to make those changes, adding a few preferences to the prefs pages, defaulting a basic 2-3 line form for classifying pages that can be modified, making it easy to modify bottom toolbars with different buttons included or not, loading the top toolbar, which is easy to modify, with extras like a couple formats of Topics list and Index...

Also, use variables %TWIKIWEB%, etc, consistently, and clean up hard references in the docs.

That's about as primitive a list as I can imagine, and addressed elsewhere in broader ways, but I'll work on that in NewContents for non-tech managers as docs... I'm sure it'll make a big difference, just that. Though a complete demo intranet would be great as well... I put this under DocsToDo.

-- MikeMannix - 13 May 2002

I have customized our Twiki installation to be as close as sensible in appearance to our "official" collaboration environment. You know, the nail that sticks out... This was quite easy by changing twiki.tmpl, and could have been done by doing a skin as well, with a little bit more work. (For users who prefer the original twiki flavor I made a skin that they can apply in their preferences if they so desire.) Part of this customization was also to install the SpacedWikiWordPlugin .

I think the ability to make these customizations is a big part in gaining acceptance.

-- ThomasWeigert - 13 May 2002

Exactly! A couple days after the stuff above, and I re-realized - I'd done this with the old template system last year - how much is hardcoded in the templates - twiki.tmpl and view.tmpl particularly - that should be VARIABLES, especially with the current template system. So, I try to imagine complete first time confusion - not out of lack of skills... How? Why? Or right to the to-do...

Templates are made to be modified, but TWiki is a special case:

• TWikiTemplates are not hard to follow, once you've checked 'em out, but at first look, they can seem quite convoluted.
• Variables are normal, but here there are VARIABLES plus template variables being defined_ and template variables being used all at the same time.
• Some of the regular variables are set through the browser, others generated by the system in context, others hardcoded in program modules, and others user-defined in the config file.
• And then, the templates rely heavily on their own variables, and have a lot of hardcoded markup, all available only by editing the files - meanwhile, there's a heavy emphasis on everything-through-the-browser admin as well, not to creating webs, even.
• So, right off, you get WEBBGCOLOR, and BLAM, the toolbar colors change...and that's about it! You can control hundreds of things through browser, EXCEPT the fonts, the colors, the fixed text. You CAN do anything in the freeform body text, but that's it. Skins, and you're back into templates.

Trying to see it from a docs side - confusion to clarity - maybe the problem some people seem to be having, who obviously have the skills to discover and install TWiki, and attempt to set up their own application, is that FIRST, after install, there's no path in, you hit a lot of simple but abundant details, and no help. Skins, templates, tips'n'tricks, preconfigured functions, all that's great, but TWiki is still:

• simple, when taken piece by piece
• should be understood by any admin to be properly used - a balance between developer's toolkit (programmers only) and regular program that does something out of the box (accessible but rigid)

TO-DO: Meanwhile, there's one simple thing that can be done quite easily, that MAY help the situation greatly: fix the main templates!

1. hardcoded settings into variables: the robot - imageHome.gif in twiki.tmpl into %LOGO%; the white body bgcolor in view.tmpl into %PAGEBGCOLOR%. Etc. And add attributes with variables.
2. heavily comment the templates: twiki.tmpl and view.tmpl. separated each section with spaces, explained what part of the page each defined, described the VARIABLES and the template defs, commented on the hardcoded stuff, made suggestions. For the view.tmpl, added a bunch of spaces in the head area and noted: DROP SCRIPTS AND STYLES, OR LINKS TO EXTERNALS, HERE! (Apache httpd.conf file style!) I started on commenting these - will post.
   • _the problem with comments in the templates is that they are passed on to the browser. Unless there is a way to comment without using html

     <!-- -->

     which I'm not aware of? This really cries for a bootstrap approach: use Twiki to build Twiki templates. -- MattWilkie _

Doing just those two things, along with a barebones version of NewContents docs set-up, could make a huge difference. It becomes a more step-by-step process getting into TWiki, fully adjusting the basic look, while being intro-ed to many TWiki features and the general set-up, while still just following instructions.

(There's some stuff in lib modules, like the kinda green on the forms and tables. Can those be pulled out?)

All this would be great with whatever else, skins, cookbooks...

-- MikeMannix - 19 May 2002

...responses inline -- MattWilkie - 28 May 2002

Templates confusion acknowledged. I have started documenting in TemplatesDocumentation.

Seems that %PAGEBGCOLOR% is left open after one year. Seems useful to me, though. Seems quite simple to implement, and by-passes the pending TWiki goes CSS discussion. Other variables that come to mind are:

• %FONTCOLOR%
• %ACCENTCOLOR%
• %LIGHTCOLOR%
• %BUTTONCOLOR%
• %BLOCKQUOTECOLOR%

Also table colors, but you can use the TablePlugin for this (you can even set a global color scheme by setting the default table attributes).

-- ArthurClemens - 01 Sep 2003