Topic: Technical writing

I’ve been trying to figure out wikis for a long time. It always strikes me that the wiki is probably the first truly unique (and successful) textual form of the Internet age. And there’s a lot to figure out. The technological innovation of the wiki is actually remarkably straightforward,¹ and while difficult the community building aspects of wikis are straightforward.² The piece of the wiki puzzle that I can’t nail down in a pithy sentence or two is how to organize information effectively on a wiki.

That’s not entirely true.

The issue, is I think that there are a number of different ways to organize content for a wiki, and no one organizational strategy seems to be absolutely perfect, and I’ve never been able to settle on a way of organizing wiki pages that I am truly happy with. The goals of a good wiki “information architecture” (if I may be so bold) are as follows:

• Clarity: It should be immediately clear to the readers and writers of a wiki where a page should be located in the wiki. If there’s hierarchy, it needs to fit your subject area perfectly and require minimal effort to grok. Because you want people to focus on the content rather than the organization, and we don’t tend to focus on organizational systems when they’re clear.
• Simplicity: Wikis have a great number of internal links and can (and are) indexed manually as needed, so as the proprietor of a wiki you probably need to do a lot less “infrastructural work” than you think you need to. Less is probably more in this situation.
• Intuitive: Flowing from the above, wikis ought to strive to be intuitive in their organization. Pages should answer questions that people have, and then provide additional information out from there. One shouldn’t have to dig in a wiki for pages, if there are categories or some sort of hierarchy there pages there shouldn’t be overlap at the tips of various trees.

Strategies that flow from this are:

• In general, write content on a very small number of pages, and expand outward as you have content for those pages (by chopping up existing pages as it makes sense and using this content to spur the creation of new pages.
• Use one style of links/hierarchy (wikish and ciwiki fail at this.) You don’t want people to think: Should this be a camel case link? Should this be a regular one word link? Should this be a multiple word link with dash separated words or underscore separated words? One convention to rule them all.
• Realize that separate hierarchies of content within a single wiki effectively create separate wikis and sites within a single wiki, and that depending on your software, it can be non-intuitive to link between different hierarchies.
• As a result: use as little hierarchy and structure as possible. hierarchy creates possibilities where things can go wrong and where confusion can happen. At some point you’ll probably need infrastructure to help make the navigation among pages more intuitive, but that point is always later than you think it’s going to be.
• Avoid reflexivity. This is probably generalizable to the entire Internet, but in general people aren’t very interested in how things work and the way you’re thinking about your content organization. They’re visiting your wiki to learn something or share some information, not to think through the meta crap with you. Focus on that.
• Have content on all pages, and have relatively few pages which only serve to point visitors at other pages. Your main index page is probably well suited as a traffic intersection without additional content, but in most cases you probably only need a very small number of these pass through pages. In general, make it so your wikis have content everywhere.

… and other helpful suggestions which I have yet to figure out. Any suggestions from wiki maintainers?

mcabber is console based XMPP or Jabber client. It runs happily within a screen session, its lightweight, and it does all of the basic things that you want from an IM client without being annoying and distracting. For the first time since I started using this software a year or two ago, there’s a major release that has some pretty exciting features. So I wanted to install it. Except, there aren’t packages for it for Debian Lenny, and I have a standing policy that everything needs to be installed using package management tools so that things don’t break down the line.

These instructions are written for Debian 5.0 (Lenny) systems. Your millage may vary for other systems, or other versions of Ubuntu. Begin by installing some dependencies:

apt-get install libncurses5-dev libncursesw5 libncursesw5-dev pkg-config libglib2.0-dev libloudmouth1-dev

The following optional dependencies provide additional features, and may already be installed on your system:

apt-get install libenchant-dev libaspell-dev libgpgme-dev libotr-dev

When the dependencies are installed, issue the following commands to download the latest release into the /opt/ directory, unarchive the tarball, and run the configure script to install mcabber into the /opt/mcabber/ folder so that it is easy to remove later if something stops working.

cd /opt/
wget http://mcabber.com/files/mcabber-0.10.0-rc3.tar.gz
tar -zxvf mcabber-0.10.0-rc3.tar.gz
./configure --prefix=/opt/mcabber

When that process finishes, run the following:

make
make install

Now copy the following /opt/mcabber-0.10-rc3/mcabberrc.example file into your home directory. If you don’t already have mcabber configured, you can use the following command to copy the file to your home directory.

cp /opt/mcabber-0.10-rc3/mcabberrc.example ~/.mcabberrc

If you do have an existing mcaber setup, then use the following command to copy the example configuration file to a non-overlapping folder in your home directory

cp /opt/mcabber-0.10-rc3/mcabberrc.example ~/mcabber-config

Edit the ~/.mcabberrc or ~/mcabber-config as described in the config file. Then start mcabber with the following command, if your config file is located at ~/.mcabberrc:

/opt/mcabber/bin/mcabber

If you have your mcabber config located at ~/mcabber-config start mcabber with the following command:

/opt/mcabber/bin/mcabber -f ~/mcabber-config

And you’re ready to go. Important things to note:

1. If something gets, as we say in the biz “fuxed,” simply “rm rf /opt/mcabber/” and reinstall.
2. Check mcabber for new releases and release candidates. These instructions should work well once there’s a final release, at least for Debian Lenny. The release files are located here.
3. Make sure to stay up to date with new releases to avoid bugs and potential security issues. If you come across bugs, report them to the developers there is also a MUC for the mcabber community here: xmpp:mcabber@conf.lilotux.net.
4. If you have an additional dependency that I missed in this installation do be in touch and I’ll get it added here.
5. Debian Lenny ships with version 0.9.7 of mcabber. If you don’t want to play with the new features and the magic in 0.10, then go for it. If you just want a regular client, install the stable mcabber with the “apt-get install mcabber” command and ignore the rest of this email.

Before I got started down my current career path--that would be the information management/work flow/web strategy/technology and cultural analyst path--I worked in a library.

I suppose I should clarify somewhat as the image you have in your mind is almost certainly not accurate, both of what my library was like and of the kind of work I did.

I worked in a research library at the big local (private) university, and I worked not in the part of library where students went to get their books, but in the “overflow area” where the special collections, book preservation unit, and the catalogers all worked. What’s more, the unit I worked with had an archival collection of film/media resources from a few documentary film makers/companies, so we didn’t really have books either.

Nevertheless it was probably one of the most instructive experiences I’ve had. There are things about the way Archives work, particularly archives with difficult collections, that no one teaches you in those “how to use the library” and “welcome to library of congress/dewy decimal classification systems” lessons you get in grade school/college. The highlights?

• Physical and Intellectual Organization While Archives keep track of, and organize all sorts of information about their collections, the organization of this material “on the shelf” doesn’t always reflect this.

  Space is a huge issue in archives, and as long as you have a record or “where” things are, there’s a lot of incentive to store things in the way that will take up the least amount of space physically. Store photographs, separately from oversized maps, separately from file boxes, separately from video cassettes, separately from CDs (and so forth.)

• “Series” and intellectual cataloging - This took me a long time to get my head around, but Archivists have a really great way of taking a step back and looking at the largest possible whole, and then creating an ad-hoc organization and categorization of this whole, so as to describe in maximum detail, and make finding particular things easier. Letters from a specific time period. Pictures from another era.

• An acceptance that perfection can’t be had. Perhaps this is a symptom of working with a collection that had only been archived for several years, or working with a collection that had been established with one large gift, rather than as a depository for a working collection. In any case, our goal--it seemed--was to take what we had and make it better: more accessible, more clearly described, easier to process later, rather than to make the whole thing absolutely perfect. It’s a good way to think about organizational project.

In fact, a lot of what I did was to take files that the film producers had on their computers and make them useful. I copied disks off of old media, I took copies of files and (in many cases, manually) converted them to use-able file formats, I created index of digital holdings. Stuff like that. No books were harmed or affected in these projects, and yet, I think I was able to make a productive contribution to the project as a whole.

The interesting thing, I think, is that when I’m looking through my own files, and helping other people figure out how to manage all the information--data, really--they have, I find that it all boils down to the same sorts of problems that I worked with in the library: How to balance “work-spaces” with storage spaces. How to separate intellectual and physical organizations. How to create usable catalogs and indices’s of a collection. How to lay everything down so that you can, without “hunting around” for a piece of paper lay your hands on everything in your collection in a few moments, and ultimately how to do this without spending very much energy on “upkeep.”

Does it make me a dork that I find this all incredibly interesting and exciting?