Report Discussion Wiki

December 10, 2007 at 10:34 PM

Long and potentially boring work story, feel free to disregard.

Many departments in the library have been asking for a document management system for quite some time. Specifically, asking for wiksi. I should know because I used to be one of the people in another department asking for them. In Reserves, with no server access, I ended up setting up a tiddlywiki on a network share drive. It worked for our three person group, but obviously wouldn’t scale much beyond that.

Desktop and Network Support (where I work now, a group in the Library Systems department) used to use (well, is actually transitioning away from) an in-house php application called SysDocs to store documentation. It worked well enough for simple things, but lacked features like effective searching, inter-document linking, etc. to be generically useful. Unfortunately, it worked well enough to resist all efforts to change it. Since I started this job last December I’ve been urging wiki software as an effective replacement.

Unrelated to work documentation, but wikis also happen to be one of the trendy library buzzwords associated with (sigh) web 2.0 that, for better or worse, are getting some major play in discussions on exactly what we as a library could be doing with this whole internet thing.

Enter a friend and coworker of mine in the Unix group of Systems who, fed up with the constant delay in actually deploying a test rollout of wiki software, went ahead and deployed a test rollout of mediawiki on our pre-development server. Happily, the first wiki he deployed was a documentation wiki for our department. Since he knew that I was a fellow advocate, he brought me in to pull over some of the documentation from SysDocs and help sell it to the crowd. I was able to do so with some success by volunteering to take charge of the content transfer if necessary. We are now in the discussion phase for rolling out wikis to departments that request them. All well and good.

Almost. We didn’t quite move fast enough and some departments have started up one or more wikis on pbwiki.com or in strange internal formats (e.g. tiddlywiki, yes I know), which my friend and I will have to (being the resident “wiki team”): convince them that moving to a library hosted wiki is better in the long run, and figure out how to transfer the data from these odd places into a mediawiki instance.

So that’s the state of wikis. Now on to the “Report Discussion Wiki”.

Every few years the library brings in a library consulting firm known as R2 to evaluate workflows and make recommendations for improvement. After a week or so of interviews and analysis the firm writes up a long report (76 pages in our case) on its recommendations. What does a library do with reports, especially a huge university library? Why, it talks about them. Meetings about the report, meetings about the meetings, committee meetings, meetings of committees, etc.

To solicit and organize comments on the entire report from all the affected staff, one of the library higher-ups was going to: get the report in word document format, turn on “track changes”, email it to the few dozen people who would be commenting with instructions to just edit and add comments directly to the document, and finally go through each of the few dozen returned word documents by hand and collate the comments and suggestions.

(a pause for that to sink in)

My boss found out about this crazy (albeit awe inspiring) plan, and decided that our brand new wiki making ability could be just the solution. Wikis allow editing and commenting from many to form a cohesive whole. So my friend was tasked with setting up the wiki instance, and I was tasked with transforming the report into a wiki format in such a way that it would be easy for non-technically oriented people to add their comments. Ah…there’s the tricky part.

Converting the text of the report to wiki formatting was cake thanks to textmate and regexes. The report was broken into a dozen sections of moderate length, so it was clear that an article with for each section would be perfect. I created a navigation box for the top and bottom of each article that let readers easily go forwards and backwards. Each section in the report was nicely organized into headers which directly translated into a semantic wiki article format. The only tricky part was that whole “easy to add comments” thing.

At first I just created a nice BIG link to the discussion page for each article at the top of each article. The discussion page had a header describing how to add comments with a link to a comment help page if they needed a refresher on syntax and the like and another BIG link to ‘Add Comment’ which was an alias for ‘edit this page’. That worked alright, but the editing window presented from the ‘Add Comment’ link had a lot of scary syntax (the header of the discussion page). Not good.

I realized that since we are dealing with non-technical people then they probably wouldn’t really feel comfortable self-organizing the discussion page with relevant headers either. So I hit upon seeding the discussion page with the same headers that were in the article. This made the discussion page nicely organized and easy to read, but even more intimidating in the editing window. Now worse.

Then came my big breakthrough: each of the discussion headers has its own “edit” link. Clicking on the edit link takes the user into an editing window just for that header section. Instead of seeing all of the headers and comments, they’d only see the header for the section they were editing and any comments made on it so far!

Using some mediawiki variables I made a generic “Add Comment” link to go at the end of each header section in the main article that takes the user from the section straight to an editing page for that corresponding section in the discussion page. I wrote a full description of the technique in my new techtips section.

Success! The formatting won over many people who thought that commenting on the report in a wiki format would be too complicated to be useful and my friend and I both got kudos at the first big report discussion meeting. Wikis, FTW!

Comments Off (7)

Designing a Report Discussion Wiki

December 10, 2007 at 02:30 PM · Posted under design, techtips

I was recently tasked with converted a large document into an easily commentable wiki using mediawiki. Here’s how I did it:

Start an article using one or more headers to organize content.

  (article)
  == Header 1 ==
  Content content content.
  == Header 2 ==
  More content.

Mirror the headers in the discussion page

  (discussion)
  == Header 1 ==
  == Header 2 ==

Now, notice that each header in the discussion page has its own edit button. We are going to use this to add an ‘add comment’ link to each header in the article. To do this we’ll have to go pass two arguments to a full weblink: action=edit, and section=(the appropriate section number). The section numbers start with 1 for the first header and increment up. To make this link as generic as possible we’ll use mediawiki variables to construct the link:

Add an ‘Add Comment’ link from the article to the corresponding section of the discussion page

[{{fullurl:Talk:{{PAGENAME}}|action=edit&section=1}} Add Comment]

Add this text wherever you’d like the ‘Add Comment’ link on the article page. I found that after the content of each article works well. So we end up with this:

  (article)
  == Header 1 ==
  Content content content.
[{{fullurl:Talk:{{PAGENAME}}|action=edit&section=1}} Add Comment]
  == Header 2 ==
  More content.
[{{fullurl:Talk:{{PAGENAME}}|action=edit&section=2}} Add Comment]

Now when users click ‘Add Comment’ on the article, they are taken straight to an editing view of the corresponding section of discussion page. Easy!

Comments Off