create new tag
, view all tags

TWiki Tool Chest

This proposal is in the same vein as EZUsabilityUpgradePlan and is geared towards simplifying the task of setting of a TWiki site that is actually useful to non-technical end-users. It also speaks to the plight of the semi-technical administrator of a TWiki site who, having survived the installation process, has limited time to implement the elements that actually provide the site’s functionality.

What I propose is setting up a repository of TWiki tools or applications. I would define a TWiki tool as an integrated set of TWikiForms, topics, templates, html-forms, and searches that together implement a particular functionality. The only example of this I have found on the TWiki web is the ItemToDo application Peter provided as a demo. I can not tell you how delighted I was to find this after I had gotten over the initial hump of getting my TWiki site up and running! This one, simple application was worth more to me than reams of documentation because it:

  1. Provided me a complete, off-the-shelf, application that I could install on my TWiki site in a few minutes.
  2. Gave me a working example that I could “take apart” to learn how the parts worked (particularly the searches) within the context of the whole.
  3. Gave me a complete working “module” that I could add on to or modify to create other tools to suit my needs much quicker than if I was working from scratch.

(Granted, the Codev web has several other examples but they are mostly pretty similar in function. Also, parts of them have restricted access so it's not as easy to copy them.)

I find myself constantly wondering what kind of really great applications already exist out there behind corporate firewalls! While I see the value of providing complete, basic, turn-key installations as suggested in EZUsabilityUpgradePlan, it seems to me that a significant percentage of what that is trying to achieve would be met by simply providing a repository of these kind of sample tools or applications. Such a repository also goes beyond that approach in that, regardless of what TWiki installation one starts from, the major work of turning this “collaboration platform” into something useful for your particular group is implementing the particular set of tools needed to support the groups particular activities. What better way to facilitate this then to offer a “toolbox” from which to choose, mix and match, modify and build upon?

This repository would serve another value of providing a showcase of TWiki “best practices.” I suspect that for many of the basic or complex applications most groups might desire, there already exist out there several eloquent implementations. I would love to see a few of those! For many, many potential TWiki users, I believe that even a modest collection of such applications would increase the immediate appeal and usability of TWiki far more than many, if not most, of the additional coding or skin enhancements that are being explored (not to diminish the value of those enhancements). TWiki is already a great platform! But we need tools to use on the platform and the learning curve of developing those tools from scratch is too steep.

What is needed to implement this? Not much, it seems to me. Peter’s example of the ItemToDo application provides a perfectly adequate working model. You simply have a main topic that provides an overview and a list of the related topics and templates for one to copy. If someone wants to provide additional explanation of how the searches were structured, etc, that would be gravy. I suppose we would need to designate a web in which it is expected to have a whole bunch of forms enabled.

In summary, I see this as possibly the greatest-benefit, least-effort options for the TWiki community to accelerate this wonderful software's adoption into a wider variety of organizations.

-- LynnwoodBrown - 07 May 2002

It's kinda funny, I mean, circular. I got here from your comment - the only one in two days!!! - on EZUsabilityUpgradePlan. Just as you mentioned that TWikiToolChest was in a similar space as EZUsabilityUpgradePlan, TWikiToolChest is a more elegantly titled version of - it gets a little complicated here - TWiki.TWikiAdminCookBook, and also a well-outlined vision of what I saw Cookbook as, exactly. As it is now, Cookbook it's a great idea, but the content is kinda, not quite there, yet, and - or because - it's missing the detailed content plan that you've written up.

Coincidentally, in literally the same few day span in which PeterMasiar launched Cookbook, I had emailed PeterThoeny about exactly the same thing, a tips'n'tricks, useful code snippets, cookbook, to add as a docs Appendix. But the idea was to have function-based sections - and, this morning in email with PeterMasiar, we were discussing working on all of this.

The first pass has each section dealing with a particular feature set. So, like, Forms & Formatted Search, RegEx Text Search - those are the core two - and then some of the non-search Variables (like INCLUDES), then Preference Variables (for, maybe, icon libraries), Selected Plugins, and then on to other individual features, of which there many. But the core TWiki functionality that is still purely Wiki (obviously everything is IMO), is fast, configurable, formatting searches of one sort or the other, taken to extremes.

So the Cookbook is a bunch of instructions describing specific applications, and cut'n'paste code with instructions. PeterThoeny's FormattedSearch is the closest (I've seen) to a an example of a Cookbook / TWikiToolChest page - it has several examples of working code good to go. It just needs more customizing and combining for specific uses. ItemToDo is fun like that. And each of those sections would be full of a variety of designed modules, suitable, with context and instructons for one or more clear common functions, working on their own or combined.

  • TIP A typical more "complex" item might be, say, a Project/Task Tracker. Once it's specced, it would be (for some) an easy matter of creating forms and corresponding formatting searches, and whatever else, then that whole thing, with a standard docs form sheet - overview, install, etc, like Plugins - you'd just pop it in as a set of pages or whatever, config, and your done.

  • TIP Another obvious extension, on the non-programming end, but just as important, is to expand the Preference Variable icons thing. I don't know if the plugin to allow variable creation on any page instead of only a Prefs page is solid, efficient. So, that's be a question. Then, upload a whole open source icon set, 30 basic office, or software, etc icons/buttons, and grid them with reference captions. So if you have a SimpleSite with minimum controls initally visible, you install, say, ItemToDo, and then pop in a nice slick button. Now, there's still the blank page, but someone comes along, sees a ToDo button, clicks it and, voila. They're one step closer to TWiki, and TWiki is still a clean canvas with one button.

  • TIP Somewhere between Manager and Developer, are semi- and non-integrated add-ons. I installed WebCalendar, multiuser, that allowed individual Public webs that anyone could post to without logging in (the user would then accept/reject later). So I linked it to the toolbar. You could enter you own stuff without logging in. It worked fine. There are a few things that fit well for some little reason.

All of which I believe is what you're saying as well.

That's happening all over, people have entered Codev in the last few months from, as I am, semi-tech land. And some developers will be helpful, but others 0 and healthy selfishness is a good thing - won't find interest in the daily pursuit of some rambling thread dealing with a very simple thing that a bunch of people are struggling not so much to code or implement, but to define, to SPEC. And the developer isn't necessarily a better designer.

That's the idea of EZUsabilityUpgradePlan: where I doubt, though I could be 180 wrong, the TWikiToolChest would ever get near even basic usability, EZ forces a complete context, a goal, that'll result in a whole bunch of modules and better ways to do 'em. As opposed to abstractly thinking up, well, a calendar, and... Instead, it's what is the minimum functionality of an intranet.

SPECIFICATIONS is the key. Without specs, Codev will pile up with the semi-tech reiterations of the same few things, some developers will get fed up with the clutter, a semi-tech ghetto web will be created... Jeeze.

Seriously, though, I am absolutely positively clear here. It's what I saw happening when I volunteered for docs (must've said that 40 times already). But now, I'm getting email from people from the distrib pack asking how to make TWiki like a BBS, just in the last month. If I spent a nice chunk of three months trying to implement TWiki as an intranet and FAILED, I should be able to breakdown the problem to some serious degree, decide what was missing, SPECIFICALLY, and then, spec if out.

It's like Sandbox.NewContents - approved. There's Users, Manager-Coordinators (the non-/semi-technical), and the Software Developers. But it takes skills to be a Manager-Coordinator, too. I can't program, but I can design, specify, know what I want and what I don't know, ask until I get answers, not get in the way, but manage, design, get execution. So that, if it can get focused, probably four-five people on here, and I'm not thinking of anyone, just the NUMBER, got with it on teh outlining side, the specs would happen, dev pages would go up, but instead of code snippets, it'd be lists, work/process flows, etc. Then a few hitmen would check out the designs, discuss, finalize, and whip it off in 3-5 minutes.

For that to actually happen, is another thing... But it'd be outstanding.


-- MikeMannix - 07 May 2002

Cookbook examples are always good, e.g. I am using the "Perl Cookbook" more then the Camel book. What applies to a language can also apply to the TWiki platform. My original idea is to use the Plugin for that. PluginPackages took off nicely, but SkinPackages and AddOnPackages are not yet as popular as I expected.

Add-on packages should be cookbook examples and best practices examples, and yes, the Sandbox.ItemToDo application could (and should) be packaged as an add-on.

We should coordinate the efforts. Currently we have Codev.FeatureHack, Plugins.AddOnPackages, TWiki.TWikiAdminCookBook, examples in the Test web, and probably other stuff I forgot. How about:


-- PeterThoeny - 08 May 2002

I agree with PeterThoeny. Using TWiki.TWikiAdminCookBook mainly for quick trick/hack was my original plan. So if we have broader topic, like tricks with Search/formatting, IMHO is better to place it in separate page, and maybe link it. Or if many additions will be added, split homegenous part of it into new page. If TOC does not fit into screen, info is not structured. I read somewhere (article about psychology), that humans can best handle 7 (+-2) items on one level of abstraction, so MikeMannix is right and we need more sections.

I was hoping more experienced users than me will add some more tricks tricks to TWiki.TWikiAdminCookBook frown

-- PeterMasiar - 08 May 2002

First, I'm absolutely delighted that my initial comments have prompted some discussion! At first, I wanted to respond to many of the specific comments, however I was dogged by the feeling that we keep trying to compare apples and oranges. I feel a real need to sort some things out, first in my own mind, before responding to some of the specific suggestions. This has lead me to digress into two new topics: TWikiDeploymentPath and TWikiTerminology. I'd be interested in seeing if folks see any value in these before coming back to this topic. Or at least I can refer to these later to backup and hopefully clarify my thoughts on this particular piece of the puzzle.

-- LynnwoodBrown - 09 May 2002

I may've posted this elsewhere, but if you haven't, read through MasterRefactor and the four projects. They're equally ignored and a separate but linked area, more on the dev side. There's this one more abstract aspect we're discussing here, developing fpr the non-technical developer - arguably, an end user, but software users don't configure custom applications, that's what...developers do for end users. But when all that's focussed, it still does come down to developing features. And there are still significant areas not yet sorted out, that have been discussed for months and more.

An example: ChangesProject, about ease of following discussions. What if I entered a one sentence comment in the body of this page, not appended?You'd see the edit in Changes, get an email alert, even, but how (easily) would you find it... There are lots of finetuning details, like that, and probably quite clear consensu on the most pessing, spread through a thousand Codev pages. So, maybe refactoring all that isn't the only way, but if people have spent a couple years discussing, describing cases, possible solutions, it's probably the best place to look. That's why documentation is everything, but really hard in OSS, where the core drive is coding, getting results. Docs ultimately mean there are hard features, and they're either clear and useful, or not. So it's almost like, at a point like this, the docs in outline can get ahead of the dev, in the sense of refinement, packaging, end user usability, of course.

And look up the few pages on Wiki collaboration - equally ignored and important. The potential to refactor, refine is there, but will people do it. Is there a way to get them to? There's tons of stuff on this in the original Wiki site, which is a software developer-populate zone, but it's not really included much. (GoodStyle sounds good, but isn't applied much.). Because if appending text, or structuring it with forms, is the direction, again, why the Wiki?

It's kind of an interesting puzzle.

-- MikeMannix - 10 May 2002

I think that if people have spent a couple of years discussing without any code being written, one part of the problem is a lack of code! Refactoring existing discussions is a noble aim, but it is a huge amount of work - this is why I didn't refactor TWikiOnWindows but instead wrote WindowsInstallCookbook, which synthesised the discussions in TWikiOnWindows.

I don't believe there is often a consensus on hard problems such as how to notify people of changes effectively, without overwhelming them, which is one reason why the discussions run on for such a long time without really concluding - often the only way to see if something would work is to write some code and then make it available as a prototype. Public TWikis have a valuable role as a way of letting the TWiki community test such prototypes, with the discussion about how well they work staying on TWiki.org - when there is consensus that a particular prototype works well, the CoreTeam can look at bringing it into the core code.

I do agree that writing a real doc, based on a number of ThreadMode discussions, may be the best way to focus the community on a particular proposed set of features, and a design for implementing them. However, there needs to be a prototyping process as well IMO, to avoid the endless discussion syndrome smile

-- RichardDonkin - 10 May 2002

A few quick comments this morning, mostly reflecting on the path this discussion has taken but mostly to re-emphasize the core point I want to make in this topic.

  • It’s interesting to me that from my starting place in this topic, which was specifically pointing to the underappreciated (IMHO) importance of what I’ve defined as TWiki applications (see TWikiTerminology), the discussion immediately took off in several directions through exploring different types of documentation, how to structure threaded discussions, the importance of refractoring (hear, hear!), and the need for more code writers (hear, hear again!). Are all of these topics totally intermingled are is it possible that we’ve got them a little muddled?
  • In my mind, each of these are distinct, different topics which, until we can tease out what we mean by each of them, are not likely to progress. This is why I would like to take a strong stand for defining our terms. Hey, “cookbook” means whatever we say it does! But let’s see if we can agree on a definition that this community can use. Is this part of what MikeMannix is referring to as “specs”?
  • The question of structure versus un-structured information is, for me, one of the most critical conversations in delivering on the potential of Wikis in general and TWiki in particular. Somewhere MikeMannix made a comment along the lines that perhaps TWiki, by combining the Zen formlessness of Wiki-nature with more powerful features and tools to provide structure, is transcending Wikis and becoming something completely new. I believe that he is absolutely right on the money there!! I propose that if we can get just the right mix of free-form wiki-freedom and enough structure that folks don’t get overwhelmed, we well may deliver the holy grail of collaboration software. OK, a bit grandiose... but I think TWiki is as close to this as anything out there.
  • Here’s the paradox: the power of freeform is lost without appropriate structure. Unless we can figure out to provide appropriate structure, the multi-colored potential of freeform wiki-nature is lost in a brown, shapeless, muddle-soup. (Kind of like my totally mixed metaphor here wink ) In my mind, what this requires is 1) giving names to things (the original act of creation and order), 2) Providing structured input through specifications, tools and applications (as launchpads for more free-form), 3) ways to encourage and reinforce GoodStyle, 4) ways to empower refractoring.
  • I’m going to go out on a limb here and assert that we don’t need to worry about smothering wiki-nature in too much structure. Wiki-nature is a powerful force of nature and it is built in to the core code of TWiki. We couldn’t smother it if we tried! On the contrary, (and again, paradoxically) I propose that by providing structure, we will only be assisting wiki-nature to come into full bloom. Kind of like how pruning a fruit tree only makes it grow more vigourously.
  • But let me return to my original point in this topic, which was to make a call to collect more TWiki applications a la ItemToDo. To my mind, these kinds of applications are a pure embodiment of the power of integrating structure and free-form. In this particular case, I differ with RichardDonkin about a lack of code being the issue. Part of what is powerful about TWiki applications, in my mind, is that, for the most part, they don’t require code. Using the foundation that is provided by the TWiki core code, a mostly non-technical person, in the simplest cases using only forms, topic templates, and predefined search, can create a pretty powerful application. Add to that a few general-purpose code-based plugins (such as the calender plugin) and the potential is truely immense! Then, on top of those applications, wiki-nature again comes into play in linking everything together and taking off in whole new, unforeseen directions as is its nature.

Forgive me if I rant...

P.S. A few last questions on prior comments:

  • Richard - Could you define for me exactly what you mean by "prototyping" in your last sentence? Others may understand, but I'm not quite clear but suspect you're pointing to something very important. If possible, give some examples in TWiki.
  • Mike - Likewise, could you define what you mean by "specification?" Not in a general sense but specifically as relates to TWiki. What would be some examples of TWiki specifications?

-- LynnwoodBrown - 10 May 2002

Heh-heh, I was getting a bit burnt out on this general discussion...until I read this just now, 13-May-2002, AFTER among other things having last night written TWikiSetUpTroubles, and read, TWikiExtraFeatures (started Mar-02, last updated mid Apr) and the related CodevFields (May 12-13, started by RichardDonkin.

  • For one, jsut that sequence above points of the practicality of a ChangesProject, parallel to an individual feature code tracker - I've obviously been around here a lot lately - look at WebChanges <G> - but missed even new relevant features that would've affected replies. It's a forest-trees thing. And, I click Changes every half hour or so if I'm on for a while, looking in part for replies - this is collaboration, right - and still missed all that...

  • RichardDonkin: re "Refactoring existing discussions is a noble aim, but it is a huge amount of work - this is why I didn't refactor TWikiOnWindows but instead wrote WindowsInstallCookbook, which synthesised the discussions in TWikiOnWindows" (I don't know what quoting blocks of text from above, email-style signifies, but...) I agree totally. That's what MasterRefactor was about - which either would've probably worked if done when I had billions of snippet locations stored away (three week TWiki.org crash right after MasterRefactor start), OR, some of the people, in collab spirit, who had originally written this stuff could've pitched in and filled in the pieces. I'm not implying any obligation, simply that, as usual, group efforts - committee government, COLLABORATION - is easier discussed than done. You personally synthesized Windows, after a couple years of others starting to, contributing, etc. and you apparently have charted one path through options to get to (one) end - but still, it's not a universal solution, with consensus as such, just a by far better one route take than existed before.
    Refactoring of ideas, as a term borrowed from codewriting, is in the case of editorial discussion, a lot looser, I don't agree with a distinction, it IS synthesis on one scale or another. And I think, from a first read, that, gathered in one spot, presentable as a mix of key quotes and, mainly synthesized outline, there IS a very clear set of features and problems, at least, and maybe some promising solution directions as well, to be distilled from Codev. If those "specs" are for insoluble problems, undoable features, then there's a big dev barrier. But perhaps the focus would mean something. Two years of discussion doesn't mean no conclusion, it may mean, not enough collaboration. Also, a lot of the "gateway" pages simply line up see also links, which doesn't really help. If a new contributor hits one of those to gind the right place to post or find info, what do they do, read a dozen or two or more pages? Or pick from title - trusting that the gateway is up-to-date, and a most-approprite topic has appeared in the last week or month since last update. In a brief Cunningham quote (yeah, loaded reference, but...), asked how he got Wiki going, he said something about anonymously just fixing up posts and adding little prods, in the background, daily, for two years. It's really that sort of work, fanatical, long-term, unglamorous, to distill - from personal experience editing a trade mag where juggling expert info from non-writers, with organized written presentation consistent with the material in full detail, and preserving writing style to justify the writier's byline, was very real.

  • LynnwoodBrown: Reading your first posts, I thought they were great, but also not unrecognized, and wasn't sure if you'd been reading around. But clearly you have, to the point of uttering the TWiki Vision, a weird one to some, absolutely, but to me, as normal and plausible as the chance of rain in New York this evening. What I meant by specifications, re TWiki, is what I got to in TWikiSetUpTroubles, at the most fundamental level, listing out executable items, just as in specced code development, but in terms of docs, and also requests for code based on specific needs for docs/deployment. So, it's like, OK, it's agreed that User's Guide is point form, quick ref, minimal reading, because it's fact that people will not read to learn, period. So, how to break down the existing pages: list the points, structure the areas - what's the first thing a person will do, first problem encountered, divide into sections maybe:
    1. Navigation
    2. First-time text-only entry (Edit, Comment Plugin?)
    3. Minimal, email/emoticon level formatting
    4. Using changes features
    5. Drastically reduced feature sets and preconfigured snippets: forms (modify a default basic page classifier), VARIABLES set (which 5-6 are really used?)

Y'know, from brainstorming - and talk - to blueprinting...

  • Before going through TWikiSuccessStories, and setting up a new TWiki yesterday, I was talking about full applications (as in your usage, I believe), until I (re-)realized that the needs were a lot more simple - actually, the basic application spec was simpler than a full-blown intranet or project platform. Just a well-documented path to a good-looking, easily brandable (logos, colors, sections and section heads), quick-to-start-using whiteboard for the Web (my quick shorthand).

-- MikeMannix - 13 May 2002

I've been reading through this discussion this evening trying to trace the thread from my original post and it's pretty difficult. It reminds me of trying to facilitate a discussion where there is no agreement about what the group is trying to accomplish, what the topic is, or what the groundrules of discussion are. Not pointing any fingers here...I'm as guilty as anyone. Just that I'm very impressed with how hard it is to "corral in" any kind of consensus around any of the deployment-related issues.

Part of me would like to ruthlessly refactor this topic and gather together all the comments that seem directly related to the actual proposal I started out making and maybe put the rest down at the bottom (including quite a few of my own comments). Right now, it's hard to figure out what (if anything) has been accomplished in this conversation. There's some great points here without some central focus, it all starts to look like a muddle (which, judging by some of the comments, might be a general description of a lot of the deployment discussions). All this has left me wondering a lot these past few days about the basic decision-making process in TWiki-dom. But I digress even further afield and will reserve this for another topic and another day.

Amidst all the noise, I had all but overlooked the specific, on-topic counter-proposal made by PeterThoeny to "Use Plugins.AddOnPackages as a repository for add-ons, cookbook examples and best practices." Are you serious in that proposition? It seems to me that this would be a significant expansion of Plugins.AddOnPackages as it currently exist. Most of the items listed there now are software modules. Adding cookbook examples and best practices (=applications?) would shift the focus and character quite a bit, or so it seems to me. However, it's a possible direction to try what I'm proposing here and would work for me. I'd love to get more thoughts on this particular option. That is, if this discussion hasn't dissapated to the point of losing everyone's attention and interest...

Still trying to sort how how best to contribute...

-- LynnwoodBrown - 14 May 2002

Edit | Attach | Watch | Print version | History: r13 < r12 < r11 < r10 < r9 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r13 - 2006-02-04 - PeterThoeny
  • 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.