twiki_application1Add my vote for this tag create new tag
, view all tags

TWiki Deployment Path

My vision here is to create a clear path for someone deploying TWiki in their organization accompanied with appropriate packages of software and documentation at each step. In my mind, EZUsabilityUpgradePlan, TWikiToolChest, TWikiAdminCookBook, address distinctly different types of knowledge and complement each other by addressing different phases and user needs in the deployment process.

In reading this topic, please refer to TWikiTerminology for clarification of how I use the words "tool," "application," "cookbook," and "toolchest."

Phases of deployment

It seems to me that there are three distinct phases of deploying TWiki, each having it's own particular needs in terms of "packages" of documentation and software components. The three phases I see are:

  1. Base installation - Simply getting TWiki up and running.
  2. Initial Customization - giving TWiki stamp of organizational identity and purpose.
  3. Enhancement and Extension - Implementing functions incrementally in responce to user desires.

User profiles

In the discussion of these deployment phases below, I will use the two roles as MikeMannix defines in NewContents, System Administrators and Managers, plus one more, End-Users. These represent to me a continuum of technical understanding and ends-vs-means focus. On one end you have the System Administrator (or developers) who have relatively high technical understanding and are interested in the tool for its own sake. At the other end, you have the end user who has low technical understanding and is not at all interested in the tool but just want to accomplish the task-at-hand.

Base Installation

  • Primary roles involved: System Administrator
  • Basic objective or motivation of phase: To get the basic TWiki installation up and running successful.
  • Primary steps in phase:
    • Downloading
    • Installation
    • Testing and troubleshooting
  • Needs in terms of software and document package:
    • The core TWiki software installation.
    • System and skill requirements or guidelines.
    • Step by step instructions for installing software.
    • Technical docs to support installation and trouble shooting core software.
  • What kind of software/docs "chunks" needed?

Initial Customization

  • Primary roles involved: Managers, System Administrator
  • Objective or motivation of phrase: To do basic customization of BasicInstallationPackage to reflect organizational identity (skins and logos), plus some specific functionalities (tools and applications) suited to the organization's particular purposes and processes.
  • Basic steps:
    • Spec out what is desired in terms of look-and-feel.
    • Download and install or custom-design skins and logos.
    • Spec out general capabilities desired beyond BasicInstallationPackage.
    • Download and install appropriate plugins, tools, and applications OR create custom tools and applications if necessary. (Side note: I suspect that this is where many TWiki deployments bog down because it is too big an effort to have to create a workable core set of tools and applications from scratch - and without these, it's hard to get end-user buy-in.)
  • Needs in terms of software and document package:
    • A "toolchest" of as many pre-designed tools and applications as possible.
    • Cookbooks both for developing functionality but also for promoting utilization.

Enhancement and Extension

  • Primary roles involved: Managers, End-users
  • Objective or motivation of phrase: To add additional capabilities as needed (preferrably as simply as possible).
  • Basic steps:
    • See a need.
    • Find the appropriate tool or application and install it, OR adapt some similar tool or application.
  • Needs in terms of software and document package:
    • A "toolchest" of as many pre-designed tools and applications as possible to use directly or modify. While the name EZUsabilityUpgradePlan would be very appropriate here, I still feel that the idea of a TWikiToolChest more directly addresses the user needs in this phase of deployment. At this stage, it's very hard to predict what a particular user or organization will need. Better to give them a well organized set of easily customized tools and applications "templates" to choose from.
    • Tips and tricks.

Does this basic breakdown of the phases of deployment and the user needs at each stage make sense? BTW, I recognize there are other needs that are not addressed here, such as on-going maintenance and trouble-shooting, but those are not exactly phases of deployment.

Other thoughts about the best "packaging" of TWiki software and documentation components to support each phase?

-- LynnwoodBrown - 09 May 2002

Comments & Discussion

In a few days, it seems like you've more or less summed up the "non-tech" TWiki developers' TWiki nightmares. It's odd reading several times the same resigned, "Well, I like TWiki but I've given up here."

In NewContents, the main point was taking the usual end user / admin/developer split in docs, and splitting the backend stuff into two sections:

  • Admin for Non-Technical Site Development (varioius managers, team leaders, techers, anyone setting up and using a collab platform, based on the usual folowing the instructions, using the features)
  • Software Developers: Site customization down to the coding level if necessary.
  • Installation: not a group, but making sure that installation and problems don't get muddled in, by focussing on the sure paths: probably still Linux/Apache root access; and maybe the same on ISPs with certain specific services.
  • End Users separate, barely a full paragraph in sight, just point form quick reference.

Also, this is a Wiki in the end, that's the part that goes over or not. Structuring out the Wiki and there's a lots of gear out there to do anything. So I don't think a more tools approach would work. There's only so many things to do:

  • intranet whatever that comprises
  • team collaboration software dev, a great train robbery, whatever; preplanning, logging, documenting
  • research & writing maybe. more text/media oriented; writing reports, fiction, research
As a quick take, what else? TWiki COULD be a...anything...but the basics if turnkey, really just allow people to approach the freeform text part, and if they start using that, well, that may lead somewhere. Oterwise, why T/Wiki...?

-- MikeMannix - 10 May 2002

First, I just want to say that I'm not at all resigned about TWiki. On the contrary, I have lots of ideas about specifical applications that I would like to develop and would love to have some more sample applications that I could build off of to shorten my development time.

That TWiki is a wiki is the core of its appeal to me. However, I don't think that this is necessarily the main selling point to new end users. They don't care about anything so (apparently) esoteric. They just want to accomplish something. In the process of fulfilling that need, they may discover (or not) this odd thing... ("you mean I can branch off a new topic here? Wow!").

A quick example. I have just introduced a TWiki site into the community where I live. I decided to use it to facilitate a discussion around a rather controversial subject. (Which may not have been such a good idea but that's a different discussion.) I simply put up a page with some positions and used CommentPlugin so no one would have to learn about editing topics (as suggested in TWikiAdminCookbook). Most people just wanted to add their two cents and did so with minimal fuss (or interest in the technology that allowed them to do so). A few were curious enough about TWiki to explore further and some actually learned how to edit topics. In essense, I used a simple structure (an simple application to post comments, if you will) to lure folks into TWiki. Once in, I'm convinced they will eventually get seduced by the empowering nature of wiki.

Regarding how many pre-defined applications are desireable, I agree with you about the basic ones you mentioned (so where are they?) but I also think there could be lots more. Actually, to my mind, the list you provided above actually suggest to me a number of particlar applications. For example, under team collaboration, pre-planning, logging, and documentation require slightly different kinds of applications. I've love to see a template application for each of these.

Project management is an area where I have more experience. Initial definition and scoping of a project requires one structure. Tracking actions requires another. Periodic reporting another. Problem management yet another. Etc., etc.

You've mentioned elsewhere your use of Filemaker. Like Filemaker, creating a new TWiki application may be very easy, even trivial, from a technical standpoint. However, I believe that most people would much rather build off of an example or template rather than create a new one from scratch. I've created quite a few Filemaker custom databases for all kinds of home and business uses. I nearly always start by searching for similar examples already out there, if for no other reason just to see how other folks have approached it. Often times, I find one close to what I want and then modify to my particular needs. Some times I learn new tricks along the way. The fact that I can easily modify the template is part of the appeal of Filemaker. I propose that this is potentially a big selling point for TWiki as well. Add to that the fact that you can create free-form links in ways that Filemaker never dreamed of and you've got something with major appeal.

Regarding the documentation, first, I totally agree with the direction you are targeting specific pieces of documentation to specific groups. Where do you see Cookbook-type documents fitting into all that?

Also, what do you (or anyone else) think about the basic phases of deployment I've outlined above? Do they make any sense to you? What I'm specifically trying to get at is the user motivations that emerge organically out of the process. Even if my particular segmentation of the process doesn't work, what about the general approach? It just makes sense to me provide documentation that matches not only the roles, but the natural stages in the process one goes through in deploying TWiki.

-- LynnwoodBrown - 10 May 2002

I think all of your topics are great and address the non-technical development/customization area directly on point. If there's any slight edge in my comments, it's from anticipation of getting this close in general and then not delivering (not you, docs in general). You've nailed all of these points in one pass, clearly and...concisely ;> - still, they're points existing spread through this site, but way less upfront. PeterMasiar in particular, has also presented the non-tech developer POV relentlessly for months. And I've been on the same track, with a bit of an extended break. Of course, there are lots of other people, but I'm just looking at the volume of recent pointed input. So, what's next?

Since the NewContents structure is improved, help working directly on that would be great. Splitting the development docs into non-tech and s/w developer suddenly means a whole new line of communication. Proofing, organizing, traffic controlling questions on the technical area is fine, and I don't have to final proof the actual code and specs. Meanwhile, simplifying the non-tech development area is a clear way to bring basic usability questions to the bottom line. Not Codev discussions, but the next step of saying: here's how to do this - or finding out, hey, that's not easy at all, how to fix?

When I mentioned the "failed TWikis", it was the dead similarity of several replies: "just couldn't handle it in the space I had to do it". And there are no examples out there! EvEm is fantastically over the top, but hardly a typical example - some kid says, I want a site like that, and the answer is, well, start by installing TWiki. Unless I'm missing something huge here, that's not it. So, docs seem to be the only example, in this strangely caseless case.

I guess that's it, bottom line. Having workflow in docs the same as in Codev. TWiki is already part docs development. Tackling sections one by one would be great. There are some excellent helpful people who are code-based; a separate docs team collaborating would do it.

Two BIG but straightahead tasks - creative planning, edit/rewrite/write, Peter/Core feedback - :

  • reducing User's Guide to something real simple.
  • tackling the division of non-tech and tech reference


(I'm, um, impressed that you read through the Filemaker stuff - I just saw it, too, one of the longer winding ones...)

-- MikeMannix - 12 May 2002

One of the key points I get out of Mike’s comments here is the need to clarify and gear up a non-code development track for TWiki. Mike’s been doing a huge effort around refining documentation and this effort deserves more structure and support. NewContents is a great start! I agree that this is a foundation piece for easier deployment and commit to give it more attention and see where I can contribute there.

Regarding the “failed TWikis” I still believe that the #1 factor in this is lack of applications “prototypes” (to borrow a term that PeterMasiar suggested in TWikiToolChest). Looking over the examples you offered in EZUsabilityUpgradePlan, the primary frustration was not issues of installation (although those are real) but what to do then. After TWiki is up and running, what’s the three most important factors is showing TWiki’s usefulness and consequently geting end-user buy-in? Applications, applications, applications! To quote RichardDonkin from HowToGetInternalBuyInForTWiki, “I do think that applications sell TWiki - if somebody finds a 'killer app' for TWiki in a particular organisation, that can really move it forward (obvious but true) - if there is no real reason to use TWiki it's hard to get it started.”

So I raise once again a call for something along the lines of TWikiToolChest. What frustrates me here (no blame, just my own impatience) is that it seems like it would be such an easy task to asked TWiki users out there to share some of the applications they’ve created and pull together some of the “best practices” from those into a set of great TWiki application prototypes. (Maybe we should start a contest for the best "killer TWiki-app" with the prize being a Twiki doll autographed by PeterThoeny smile .)

So the #1 question I have for the fledging non-technical development development track is: how do we float a proposal and get approval for creating some kind of repository/demonstration area for pre-configured TWiki tools and applications?

-- LynnwoodBrown - 13 May 2002

Working on this has been from the start, well...educational, and interesting. Also, lots of work, when I've stuck to it. At the very beginning, when I had time, I spent 10-15 hours a day, a lot of it just reading Codev and existing docs, in a fanatical rush of enthusiasm. This phase now is equally interesting - the kind of stuff you read about (if that's the stuff one reads ;>) in Confessions of an Open Source Developer and all that. And one of the big themes is the docs hurdle. Even on, say, the Apache site, reading the intro stuff, you can see the split, the "you can contribute even if you're not contributing to code" flavor. In OS projects. at least, it seems to be almost two tribes, the code side charging ahead, and, at some point in some projects, things getting ahead of the developers, where, the documentation (and packaging as an extension of the same) begins to determine the audience. And there's no doubt in some cases, a bit of a clash between some original developers, and, the extent and nature of...docs.

In any case, after a few days of reading and writing about a lot of "pure deployment", it gets blurry. Yesterday, for practical reasons, I sort of went back to basics - see TWikiSetUpTroubles - and realized that, as usual, things are pretty straightforward when you see through to core.

I also found CodevFields interesting, a little annoying personally, maybe relevant to this docs phase. CodevFields seems to have started in TWikiExtraFeatures, where the original comment was about having a hard time keeping track of new features and fixes. I dunno if a new web form will sort things out - it takes upkeep, and the Codev pages are just multiplying with little refactoring - but a decent classification form is necessary. Clear docs seems to be the one solid ground, a black-and-white area: instructions work, information is clearly supplied and questions answered, or not... It's interesting how docs has become a bit of a dev area. I put in a form in the public TWiki docs to be able to quickly sort out "official" pages from other stuff. Probably, deployment issues related to configuration using standard production features - or the lack thereof - should be moved to the TWiki docs web. Completed features in Alpha are documented in TWiki, so it's a dev area as well!

Within that approach, the cookbook/toolchest becomes naturally integrated, and if a certain chunk of functionality seems crucial, perhaps that can bounce back to Codev as a FeatureEnhancementRequest coming in on a different channel.

-- MikeMannix - 13 May 2002

I just found this after looking for an appropriate place in Codev to link to a topic I've created on a similar material. Maybe we can merge ideas. NewTWikiAdminSteps

-- AmandaSmith - 15 Feb 2006

Wow. Who wrote all this stuff? I sure don't remember it. wink Thanks for the walk down memory lane, Amanda. Ancient history. We're way past that now.

Oh, wait a minute... I'm still waiting for that TWikiToolChest to help non-tech admins go the step after installing TWiki. Come to think of it, that's basically what I've been trying to create with TopicClassificationAddOn - a simple set of TWikiApplications that folks can customize and build on. Maybe we're just getting to the point where we can have this conversation. I wish MikeMannix were still around to see it. He had the vision of it back then also.

-- LynnwoodBrown - 15 Feb 2006

Well I may not be able to contribute to the coding of an improved installation for non-tech (or semi-tech in my case) admins, but I can certainly work on the documentation to make it easier to understand for us non-perl geeks. I would really like to work more on this.

Yes, I know that the whole idea of a wiki is that anyone can go in and edit. But, I also feel like I haven't been around long enough and developed enough of a reputation to start doing some serious hacking to the distribution documentation without a bit of backlash. I would really like to improve this whole experience for new people. So those of you who've been around this block many times, please let me know if you feel comfortable with me getting in there and doing significant documentation revision. Should I create new topics (in the style of ExistingTopicNameRefactored) with my refactoring for approval of the core team, or add suggestions to the bottom of existing topics which can then be merged in? I think the first method might be best, to just create it as a new topic with the total rewrite so that everyone can see it, add to it and decide if it really works before we copy it into the existing documentation topics.

-- AmandaSmith - 15 Feb 2006

Hopefully, DakarRelease has improved the ease of installation some.

Your interest in improving the doc in modest or major ways is very, very welcome! I totally agree that there's plenty of room for improving them to be more understandable to non-technical administrators. At the same time, often times that involves providing more extensive step-by-step instructions that more technical users don't need - so perhaps this can be added to SupplementalDocuments.

Here's some other suggestions in response to your questions above:

  • If you want to do a major refactor of an existing topic, work up your revised text on your site and then post it in the Discussion section of that topic in the TWiki web. Then, after some other folks have reviewed and added their comments, we can replace the original text when we're reviewing the docs for the next release.
  • If your changes are so extensive that they suggest a whole new topic, consider posting here in the Codev as a new DocRequest (ie explaining both the need and your suggested documentation).

Thanks so much for your interest in helping with the Docs!

-- LynnwoodBrown - 15 Feb 2006

Edit | Attach | Watch | Print version | History: r14 < r13 < r12 < r11 < r10 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r14 - 2006-02-16 - LynnwoodBrown
  • 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-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.