[ptsefton.com] | [CV & Bio]

ADFI collaboration and documentation tools


Shirley Reushle has been beating me up1 about the mess of software and websites and stuff that we use here at ADFI. There's ICE and Microsoft Office and OpenOffice.org and SharePoint (about which no more will be said here) and delicious and the dreaded Twitter and our multiple Trac project management sites (CAIRSS | The Fascinator | ICE and more) and some of us have blogs and some of our projects have a project blog and then there's email using the corporate Microsoft Exchange (many of us are stuck using the feeble web client for that because of our choice of operating system), and a few of us prefer to deal with our mail in the vastly more efficient Google suite. We use IM, that's instant messaging, AKA chat. Me, I talk to various team members and colleagues on MSN, Yahoo, AIM, Google Talk and Skype. Of course, everyone should be hooked-in to a feed-reader of some kind, although lots of people around here don't seem to know what that is. Stay tuned if you are one of them. Really, this is important. There's Facebook too which doesn't seem to figure too much in our work but is useful sometimes. Why just recently I saw two senior people chatting about how they have this terrible problem with how to spend tens of millions of government dollars and I was able to place a well-timed telephone call (don't they know that's what Twitter is for?). This is not counting all the stuff our virtual Worlds specialist, Lindy McKeown uses.

To help Shirley, I thought I'd sit down and do a matrix of tasks mapped against the services you can use to get them done so she could look up what she wanted to do and it would tell her which tools to use, only I can't.

It's too hard.

We do have a bewildering array of things to deal with in our work at ADFI and it takes time and practice and experience to know what to do with them all. What I'll do here is:

  1. Run through some thoughts about the various kinds of tools we use and then cook-up just a few workflows that show which applications you might choose in different situations.

  2. Following all that I'll talk a bit about what I think the future might bring, both for us at the ADFI and more broadly. To jump ahead, if the promise ofGoogle Wave is realized then a lot of the distinctions between communications software and document editors and publishing systems will disappear, but I'm sure we'll still be able to confuse ourselves.

I will follow-up with two more posts, one on how to get started with communications tools (summary, get Google Reader and find some professional sources, some journals, some news you want to follow, some photo albums from friends, get comfortable with it, then get a delicious account and start sharing bookmarks with your team, then try Twitter). The second will be about how we can bring all these things together onto an ADFI website.

Email and when not to use it: communications tools

Email is obviously a big issue and everyone claims to have too much.

Personally I follow a variant of Merlin Mann's Inbox Zero approach (check out the video or the posts). I try to either deal with email the first time I read it or add it to a task list (Gmail is great for this). Part of this is being honest about how much I can deal with I know there's no point in letting something that's of only peripheral interest to me sit around in my inbox staring at me and making me feel guilty. So if can't be answered immediately or it's not for someone who really matters like a DVC or a customer or a key stakeholder then I bin it. The alternative is to think I'll get around to that; then surprise surprise, to not get around to it; then to have to trawl through it later. Takes longer and achieves nothing but increased anxiety. They key to Inbox Zero is to turn email into action. Either that or vaporize it.

One of my priorities with my team is to reduce the volume of email that needs to be managed. By managed I mean kept, and tracked beyond the first time you read it. It's not really the total volume that matters, it's the management overheard if you can scan it and act on it it then it is dealt with, it's the things that hang around that are a problem. There are a couple of things for which I don't think email is a good solution:

Jobs to do. Actions. : If there's a job for someone to do we aim to use a job ticket2 in the Trac system, like this one I picked at random. It shows work Oliver has been doing on reorganizing one of our systems. This is much better than email, of course because it is accessible to everyone and it's all in the server not smeared around several inboxes. So for the techincal team it is standard practice to convert emails into one or more Trac tickets.

Notification of new content : Another thing that's not a good use of email is to get updates from web sites, or journals or whatever. Far better to use a feed reader/aggregator. I am frankly surprised how little penetration these systems have had. I won't name names but a lot of people who we associate with don't use an aggregator to monitor what's going on. I have Google Reader set up to watch lots of tech blogs, a few journals, some miscellaneous blogs for fun, some friend's online photo albums, some delicious tags, a Twitter search or two. I just read the whole lot, river of news style, usually starting at home around 6am but some people prefer to read by subject or by importance with folders like 'check hourly', 'check daily' and 'check monthly'. : For example, I just accidentally subscribed to the forum at a 'Virtual Conference' which is being run in what seems like hundreds of twisty little Moodle discussions, all alike and was immediately inundated with email. I wouldn't have minded all that if it was in Google reader where I could scan it but discussion like that does not belong in my inbox, and there seems to be no way to subscribe using Atom/RSS (and no I don't want to set up a rule or filter for every subscription routing email to a folder is just a way of admitting you're not going to read it or turn it into actions).

Links to look at : Then there's the one where someone sends a link to a web site in email - hey check out this cool thing if they just mail it then it ends up living in several inboxes, with no guaranteed corporate memory that it was ever sent. That's why we encourage people not to circulate links by email but to bookmark them in delicious. On the RUBRIC project we had the well-organized Marisa Parker bookmarking things as they came in via email. The result is now we don't have to go back through old mail to see what was important on the project. (One of the problems here is that some senior people are used to being fed stuff by email so sometimes we just have to send stuff that way some of them even have personal assistants and such to print out the web pages and put them in folders.) : Slightly better than sending links via email to individuals is sending them to a managed list, for which we mostly use Google Groups now. At least with a group people know they can delete their copy of a posting and it will remain in the archive but it's still not a good place to store links to websites you can also appoint a delicious user like Marisa to record stuff as it comes in (I thought you should be able to subscribe to a feed from a Google group in Google reader, but it doesn't seem to work at the moment). : Our main tags are: usqadfifor general stuff and adfisdt for stuff that is of interest to the software development team.

As I write this, in another window I see this tweet (that's a Twitter message):

billpollock always read email with the Reply button

Actually, that sounds like bad advice, better to say Always read email with a finger over the delete button, but not to worry, this brings us to Twitter. Here are a few examples of how Twitter has been useful to me and the software team:

  • Twitter's a good source of useful news and links if you follow authoritative sources with a high signal to noise ratio. Take Tim O'Reilly (the publisher). His feed is here. If you're on Twitter you can follow him, or use the RSS feedto subscribe, just as you would to a blog, so your feed reader keeps track of it all for you.

  • Twitter got me a trip to the Developer Happiness days workshop in London. OK, I admit that's stretching it, because I was known to the organizers but we had been hanging out on Twitter talking about tech stuff and David Flanders contacted me about coming to the event via Twitter.

  • Twitter was useful in developing the idea for and promoting The Fascinator in conversation with Jim Richardson, Rowan Brownlee and others.

  • At conferences now, Twitter is a really useful channel for establishing contact someone will announce where they are and a party can coalesce. See Jim Richardson's delicious links about Twitter at conferences. See that's Jim working as an eResearch hub using the tools I'm talking about here. He'll drop a link to those resources in when people start talking about an upcoming conference.

  • You can get instant advice from followers and others who happen to pick up on keywords in a tweet. Just this week, when I bought a new Android powered smartphone (to explore the digital future, not for frivolous reasons), I got lots of advice from Twitter about whether or not to buy a particular model and what apps to install on it. Similarly, I have some generous help in working out how to rescue some document in legacy formats from Twitter followers.

  • It keeps the social conversation going in our team in and out of business hours. Last weekend Bron Chandler and I were talking with Linda Octalina about (a) not working on the weekends and (b) where to buy laying chooks in Toowoomba. Doing this on Twitter means that anyone in overlapping group of followers can join in, or politely ignore us, or unsubscribe if our signal to noise ration drops too low. If we direct the messages '@' each other then they don't spill over into the the general feed. So a message from me starting with @linda_octa goes to her plus our mutual followers.

We're trying out Twitter with the CAIRSS service too. There is an officialCAIRSS account that Kate Watson and Tim McCallum use, but anyone can contribute to the conversation by using the hashtag #caulcairss in their message I can't say it's had much impact yet but we will see.

One of the other things we're trying with CAIRSS is aggregating activity from different services together on the CAIRSS site. That's only part of the story though, as that page is just taking a live feed from other services, not actually bringing the content back into a repository at our site. This is important, one of the issues with using Twitter is that messages disappear, in Real-time systems hurting long-term knowledge? Robert Scoble notes that Twitter and Friend Feed (which I will spare you here because it's not a big part of how we work) are both much less effective than blogs when it comes to persistence and retrieval, for now anyway. Which bring us to blogs. I will pick up on this idea of persistence at the end of this piece.

I think we're past the stage where we have to argue for the effectiveness of professional blogs so I'll be brief here. This blog has helped me to establish a small professional network. This blog was the glue that helped me to get to the point where I could essentially invite myself to Microsoft Research in Redmond, and get away with it. This blog is where most of the real scholarly communication I'm engaged in goes on anything that makes it into a paper or a conference presentation is already pretty well worked out and discussed here first. This blog talking to other blogs built the partnership we've established with Peter Murray-Rust's group and Cambridge.

Others on our team have blogs that work for them in different ways. They can comment below if they want to spruik them.

Finally, chat is really useful we use it a lot over lots of different Instant Messaging services. Even if you're sitting next to someone it is sometimes better to interrupt via a chat session as it means they can finish the sentence they're typing or ignore you if they're busy. I have a network of people in chat I can call on for instant advice, and some people come to me with questions too.

With collaboration tools we all have different profile. On Twitter I tend to follow peers, people with whom I have a reasonably symmetrical relationship, where it is likely that if I mention them in a tweet they will see it and maybe respond, whereas Tim McCallum gets a lot from authorities who have thousands of followers, something I use an aggregator for I would be more inclined to subscribe to Tim's pick @smashingmag in Reader than to follow them on Twitter.

Just to tie this together a bit this week a real example of these communications services in action.

Christiaan Kortekass from UQ tweeted:

ckortekaas Trying to figure out how to enable phrase stemming in Solr. Anyone know? Eg search "Andrews, K" to return "Andrews, K" and "Andrew, Kathy"

I saw this and was just putting together an email to put him in touch with Kent Fitch at the NLA who is a real guru this area when Christiaan grabbed me in Google Chat and we had a quick discussion about it, and he showed me some cool stuff they're doing with geolocating their repository access stats. While that was happening I started an email thread which ended up with five people on it. Christiaan was tweeting solutions a couple of hours later. (He makes a reappearance in the conclusion of this post).

Writing Documents

Having looked at interaction-based services I will look at documents. This is something we think a lot about, because the team at ADFI were responsible for inventing and building ICE, so naturally we eat our own dog food3.

ICE was built for making book-length courseware that can be delivered in print and web formats from the same source, with an authoring tool that academics will actually use. But we also use it for lots of other things.

  • For websites, like the ICE site, or the CAIRSS site.

  • For papers and posters.

  • For blogging. You're looking at mine now. For other examples the CAIRSS blog and the ICE blog. (And Peter Murray Rust has joined us at his blog where he is finding lots of bugs for us.)

  • For grant applications and other formal communications where PDF is a good deliverable.

    (See, I'm not anti-PDF. It's a great way to send stuff to project board members who you just know are going to print it out they'll value it much more than an email with the same text in it, and for some people a PDF is so much more authoritative than a web page. Don't worry, they'll retire soon.)

Others use it for the above as well as for newsletters which get mailed around USQ.

The basic rule here is that everything that is going to be a 'finished' web document or delivered as a PDF finishes up as an ICE document, but it doesn't necessarily have to start that way. It could start in an email, or a wiki or in Google docs.

For internal document we can circulate a document for comment just by sending a link to the ICE server and people can comment inline. This allows paragraph level annotation, which is good for general review and for discussion. There would be more work to do to make this usable by a broader population, allowing an author to set up an ad-hoc group or mail an obscure URL.

Here is an inline comment from Shirley with a reply from me:


Shirley is working on a reply to this document of mine.

Another way to collaborate is with Google Docs, which is a bit of an odd beast. I've covered it here several times before, mostly from the point of view of how broken it is at basic stuff like HTML formatting and at importing and exporting word processing documents. I have been giving it a try this week with a post I'm writing for CAIRSS about person-identifiers, where I want input from people elsewhere and I ran into a really annoying issue where it would not even import the document a plain-old OpenDocument Format document written in the latest version of OpenOffice.org. Saved the OpenDocument as a Word doc but it mangled a diagram. In the end I had to convert it to a bitmap. And when I go to re-edit and post to the blog I'll have to put back in all my styles that Google took out and put back in the original image. I used to be worried about this, but now I think that GDocs is going to be irrelevant, I'll talk about that at the end of this post. I think it's pretty telling that Google Documents doesn't even support the latest OpenOffice.org format, why would they invest in it with Wave coming?

But for all that, GDocs is spectacularly good at syncronous and/or asyncronous collaborative editing. I think Google are onto something there.

And then there are wikis. We have those too, because they are embedded in Trac. We use them for project management quite intensively. I know that Duncan Dickinson on our team is disappointed with the limitations of the wiki system in Trac, but the really good thing about is the integration with the other parts of the system. Wikis are inherently flexible so you can do a lot with them. Two things we tend to do a lot of:

  1. Put up a project summary page with a broad outline of tasks, and then link that to individual job tickets. See this one for the ICE-TheOREM project we did for Cambridge. Those crossed off ticket numbers link to tickets, which in turn link to changesets in our open code-base.

  2. For teleconferences we set up a single agenda/meeting page and take the minutes as we go. Participants can come back later and make changes as needed, which are all tracked. This does away with the whole minutes, agenda, voting to accept the minutes dance that used to go on.


I think the discussion above shows that the idea of a tool matrix with what to use in every situation is unrealistic. But here are a few common recipes for use at ADFI.

Writing a research paper using a supplied template

We have used the first two of these will try the third.

In all cases we would use a reference manager. I mention Zotero here there are others. With Zotero you have to build the bibliography and inline citations using just one Zotero library, but it does have collaboration tools which are getting increasingly good. For example on a paper we just wrote I managed references but Duncan created a lot of them in his Zotero account and shared it. Here's my account if you like any of those refs and you're running Zotero in Firefox you can click to download to your own database. (There's some kind of bug where it keeps adding duplicates, I haven't looked into yet).

+--------------------------------------------------------------------------+ | Free Range Style | +--------------------------------------------------------------------------+ | 1. Draft in GDocs with rich collaboration | | | | 2. Lead author prepares final draft and insert refs in Word + Zotero | | | | 3. Someone converts to template | | | | 4. Submit | | | | 5. Submit to ePrints using the file prepared earlier. | | | | In this model you can't go backwards <span | | class="spCh spChx2013">– once you start adding references using a | | citation manager you can't put it back in Google Docs. | +--------------------------------------------------------------------------+

Towards a manual for a new bit of software

As we write new software this is what we tend to do about documentation:

  1. Initial how-to will be in the Trac ticket or the code the developer writes, maybe in the form of a 'usage' output for commandline tool.

  2. When we get someone other than the developer to test the tool there will be a wiki page, describing, say how to install it. The tester can fix any issues with the doco.

  3. When we release, one of the project coordinators will paste the wiki-generated documentation into an OpenOffice.org document in ICE and clean it up to follow our guidelines for procedures.

  4. We publish the 'real' procedures etc on the web via ICE.

A blog post like this one

For substantial posts like this one, I tend to seek review from the rest of the team, so:

  • I write it in OpenOffice.org,

  • Interact a lot as I go in email, chat and Twitter,

  • Put it into an ICE server and get comments (or not if they are all too busy doing real work).

  • When it's done I hit the Atom Pub to push it to a blog, usually here, but if I am speaking on behalf of a project that it will go to the relevant blog.

  • Track the comments on the blog and respond there.


So it's complicated integrating and moving between all these different tools, but as I have flagged several times above, there is a potential solution coming. If that's not Google Wave then I bet it will be something that looks a lot like it.

We are working in a world where the old metaphors are still constraining use.

  • We built ICE because the metaphorical typewriter that is the word processor is not hooked up properly to the web. Yes 'web' is a metaphor, but we all understand now that it has well and truly transcended that metaphor.

  • The metaphorical postal system that is email is still well and truly mired in its own metaphor, with boxes and postmasters and so on cropping up all over the place in the lexicon. We interact with our metaphorical postal system via the web in 'web mail', but it's not really of-the-web.

I said I'd come back to Christiaan. While writing this up I remembered that yet another communications system, which they used to use at UQ, is Campfire; a group chat system that provides a 'room' where developers can drop in. When we were evaluating Fez I joined Christiaan and team at the Campfire and it was a great way to participate in a discussion with a whole team. While I was asking about how the software worked they were talking about the work they were doing, taking coffee breaks, cracking jokes just like visiting any office staffed by extremely talented and cool people.

In writing this, it was easy enough to call up Christiaan in Google Chat to see if they still used Campfire. I got my answer, but I got something else as well; affirmation. He suggested that he saw Google Wave replacing a bunch of current tools wikis, blog, email, im.


+--------------------------------------+--------------------------------------+ | me | Hey there | +--------------------------------------+--------------------------------------+ | CK | Hi | +--------------------------------------+--------------------------------------+ | me | Just writing up some stuff about how | | | we use comms tools here - do you | | | still use the campfire? | +--------------------------------------+--------------------------------------+ | CK | very much so | | | | | | though im hoping we can swich to | | | google wave at some point | | | | | | probably switch a lot of stuff over | | | to wave by the look of it | | | | | | wikis, blog, email, im | | | | | | fez.. [This is a repository | | | application that CK leads - PS] | | | | | | :P [This shows that he is joking - | | | PS] | +--------------------------------------+--------------------------------------+ | me | I agree that's what I'm wirting up | | | essentially | | | | | | Do you have a test account / written | | | any widgets yet? | +--------------------------------------+--------------------------------------+ | CK | no i havent signed up to wave yet | | | | | | have you? | +--------------------------------------+--------------------------------------+ | me | I started but I didn't click submit | +--------------------------------------+--------------------------------------+ | CK | we'd probably want our own local | | | wave | +--------------------------------------+--------------------------------------+ | me | yep | | | | | | Need to start somewhere though | +--------------------------------------+--------------------------------------+

I'm pasting this in here, with permission, because I want you to think about how this workflow might change. I am writing this in a word processor and hopping out to the web browser to look things up and paste in links, and if I want to ask Christiaan a question then that happens over in another tab in the browser and unless I make the connection like I did here, that connection is lost. I'm very unlikely to remember the contribution he made, and others commenting on this post before I publish it wouldn't see it. In Wave, I'd simply invite him in to my draft document and the chat could take place synchronously or asynchronously as we like. As it is, I have to send him a copy of this document because he doesn't have access to the private ADFI ICE system where I am going to seek comment from others.

In Summary.

  1. We need to look at Wave. If we don't then we're not much of a Digital Futures Institute4.

  2. There are no simple answers to 'which tool should I use' part of our job is to try stuff out and help others (peers, students, bosses) to create their own personal learning/research environment.

I need to follow up with at least two more things:

  1. A how-to for people who'd like to work with us and share some of these ways of working and/or thinking.

  2. A discussion about what it means when I use and recommend these proprietary tools like gmail how do you make sure your data are preserved, and how do you pull all these things back together to give outsiders a view of what we do? That post will consider at what an ADFI website might look like if it were based on a repository which pulled all these disparate services back together into a coherent view of what we do.

1 Not literally yet but she's looking like she might she actually mimed putting her hands around my neck this morning. I think the only thing that saved me is that I'm getting a sore throat and she is afraid of catching it.

2 I can hear my staff grinding their teeth here as I have a bad habit of sending them emails about software bugs or whatever instead of taking the time to put a job ticket in our Trac system.

3 I worked for NextEd for a while, one of the things that endeared me to the company initially was seeing Paul McKey's cutting up the cow keynote at AUSWEB 2K where he referred to Eating our own dog shit. He denies it, but I swear that's what I heard. Paul is no longer just a man, he's now a brand, which you can experience for yourself .

4 We could call it the Queensland Digital Futures Institute and revive that old joke about 'you are entering QLD, turn back your watches 20 years'. The the past would become the future and we could study that. Much easier.