CM Banker wrote: > Scott, I'd like a backgrounder on the TWIKI thing as well. I > experimented with a wiki setup and simply had issues or putting it > into practical use. It seems that for a wiki to work, one would have > to define it in excruciating detail or risk it coming scattered in > normal usage. >
You know, you would think that, but in practical use, we really haven't found that to be true. I suppose if your organization has strict documentation format requirements, this wouldn't be a good fit. And you could break up a twiki into multiple "webs" each with its own groups of authors/editors who control the content underneath. We've been using twiki (http://twiki.org) on our team for about two years now. Our team consists of unix, mainframe and storage administrators and engineers. We have a multitude of projects as well as daily operational responsibilities to keep track of and while people in the group have their particular points of focus, we all need to be aware of how to pick up some of the other responsibilities. When I got here, they had a system of formal documentation through word documents. They were version controlled in the sense that you stuck a version number in the header and there was a rigid corporate standard for how they should be formatted. It didn't work because most of the procedures were out of date. Things simply change to fast Also, a lot of the expected format items really didn't make sense. And so they were hard for people to write. Despite this, people were keeping documentation. They were just doing it in their own home directories. Lots of little, "howtoaddadisk.txt" files and the like all scattered about. I wanted to do something about that and I looked at Wiki solutions as well as some CMS stuff like Zope and plone. I settled on TWiki. 1) no database - it uses built unix rcs and diff tools for version control 2) perl. yeah, I like python too, but I knew perl better and could implement mod_perl for performance benefits at the time we stood this up. That said, I've done no coding for this. 3) I figured out how to hook apache into corporate ldap. So all company users could see our documentation (except for documents we might want to explicitly limit) but only users configured to do so within twiki could author/edit content. As part of becoming a member of our group, part of the checklist (maintained in the wiki, of course) is to add the user into the twiki environment. 4) the server was a spare. the software was free. Originally, my thought was that this would not replace the original formal documentation standards, but augment things so we'd have some real useful documentation that we could refer to to get our jobs done. The reality is, we don't use the formal documentation anymore. When its required, I can supply a direct link into a document in our TWiki which is visible inside the company and thus other folks can review it. Again, the version control is built in so if a version changes, it's very easy to see within twiki what changed, by whom, and when. We use numerous add-ons, some of which shipped with it, and some of which we added after the fact 1) I found a macro set for word that converts a word doc into the twiki shorthand. this allowed me to import several documents easily 2) There is a WYSIWYG editor that you can cut and paste to and from Word. 3) we can export to PDF easily for "static" documents 4) there is a Q&A component which allows users to post questions so we can build up FAQ pages 5) We use an add-on call PublishContrib that exports the entire twiki to static html. We then replicate that for Disaster Recovery. The documentation is not pretty much critical to day to day operations. 6) every day we mail the "changes" out to the group so everyone can see what's been added or updated that day. Organization of the content was originally a big concern for my boss. So we laid out the front page a little bit with some basic thoughts on how we thought it should be organized. It was pretty straightforward. The front page is essentially a page of links into other subtopics. Those are typically organizational pages as well. It's only at the third level that you get to the "meat" so to speak. And of course, it's all searchable. For example, we do a lot of Project work. so on the front page there is a link to a front page for the project, eg, FooDeploymentProject The FooDeploymentProject page then is well organized with some sub-pages containing items you would expect such as a description of the project, contact list, contract and support details, links to project manuals. Following that on the same page, are links to procedures we've written up. We came up with a template for projects and items and pages that we expect to see for every project. It's easy to cut and paste the intial template and create the expected project pages. After that, it's pretty much free-form.
