This is the fourth post in a series on collaborating with Tinderbox and version management software. Previous posts discussed:

1. Tinderbox and Version Management
2. Backing up and Version Tracking with Git
3. Git, Tinderbox and Online Repositories

This post explains some practical ideas for how to actually use Tinderbox for collaborating, a template file on github, and lots of screenshots.

Contents of this Post

• When not to use online collaboration
• Introducing the Tinderbox Collaboration Template
• Workflow Overview
• Recognizing changes in diff (boring, and helpful)
• Patterns for Collaborating with Tinderbox

When Not to Use Online Collaboration

This post is about collaborating online, when the participants are in different places or working at different times, and need use of a shared repository for their document. If you're all in the same room, use a scribe. Mark Anderson, Robert Brook, and I have all found Tinderbox to be great help in meetings. This kind of collaboration really needs only one Tinderbox user.

The Tinderbox Collaboration Template

Ever since around 2004, when my brother and I gave a joint lecture on Parliamentary Procedure (fun!), and prepared the lecture by emailing Tinderbox files around, I have been collecting ideas on how to work together on a single Tinderbox document. The Tinderbox Collaboration Template includes the basics which I find helpful for any collaboration:

• Individual Prototypes for each user's own comments
• A personal space and note for each user
• A trash bin
• Notes
• Legend for Prototypes
• Meetings
• Recent Changes
• Metafilter color theme (Happy 10th!)

Workflow Overview

To set up the template, you can either fork the project on Github, or check out the project, and push it to the repository of your choice. From that point, you do the following things to set up the Tinderbox file with your team:

1. Give each person permissions to check out and commit changes to the project
2. Create a new personal space for each person, and a new set of comment prototypes for them
3. Each person (or a newcomer) checks out the latest version and jumps right in

When actually collaborating, the workflow looks like this:

1. Work on your stuff
2. git pull to checkout others' contributions when necessary
3. You should be the primary user of your personal space. Use it extensively, and only drag things out into the main areas when your things are ready to show the others, or if you need others' comments and contributions
4. commit and push your changes when you have something to contribute
5. commit, push, and pull often, to prevent conflicts (this is contrary to software dev practices, where everything has to work. This is a document, not a computer program, so this shouldn't be a problem)

Recognizing Changes in Diff

GitX will show you changes you have made. GitHub will show you changes which others have made. Since GitHub and GitX only know about XML and don't understand Tinderbox, the output of diff can be confusing.

Over time, you will can a sense for what it all means. I hope these screenshots of diff can help give you a head start:

• New Links Added
• Boderer and Color Changes (GitX)
• Border and Color Changes (GitHub)
• Two Notes Added Next to Each Other
• Attributes Added, Text Added to note
• New User Attributes Added to Tinderbox Document
• New Color Names Added to Tinderbox Document
• Document TextFont Preference Changed
• Adding and Annotating a Picture in Map View

Patterns for Collaborating with Tinderbox

The following set of recommendations are based on my experience, so if you have further idease, please write.

• Don't limit yourself to one file. In cases where lots of changes are being made frequently, it might be best to have a separate file for each person, and to designate one person to keep a composite document up-to-date. If you all share the same prototypes, it should be simple to drag notes across Tinderbox documents.
• Recent Changes is your friend. If an agent produces too much noise, then ask people to create a "Recent Changes" area in their personal space. Before they commit and push a set of changes, they can create aliases of important changes and drag them onto the recent changes landing area. Much quicker than describing the changes, and it also gives others ready access to what each person thinks is important.
• Independent master files like this one simplify the task of starting new things. As people develop generally useful features within their project files, drag those features into your master repository so you have ready access to them when you start your next collaboration.
• Split large documents into sub-notes, so people can work on different parts without stepping on each others' toes. Nakakoji View is your friend.
• What to do when you try to push something and Git complains about a merge conflict (giving the error "needs merge"):
  • Git creates three files- your old local copy, the latest version from the repository, and a mutant hybrid of the two which you need not worry about.
  • Open up your local copy
  • Open up the repository copy
  • Find the things in your local copy which you have changed, and drag them over into the repository copy. (because while you know what has changed in your copy, you don't know what has changed in the repository copy)
  • Save As the original filename
  • Delete the extra files
  • git add, commit, push
  • (this is an ugly solution.I'm working on a better one (a) (b))
  • Always remember to commit before you pull
• Want to record who went to the meeting, or who should be working on X? Simply drag aliases of their personal space into an area.
• Tinderbox is great for arranging things just how you tend to think. If you bring that attitude to the common spaces in a collaborative file, you will spend more time explaining than collaborating.
• Messy things with lots of lines and structure are often hard to understand. Seek simplicity, and don't be afraid to have lots of clear, simple areas. In Tinderbox, choosing a few relevant things to show is often harder, and more valuable than just dumping everything on the rest of the team.
• Deleting is bad. Deleting other people's stuff is really really annoying. You might end up deleting something with 50 aliases and render your entire project incomprehensible. Just drag something to the side, or use the Trash Can if you must.
• You know this already, but do remember that sometimes you just need to go out to the pub, share a sandwich, or pick up the phone.
• Write me if you have other good ideas you think I should share