Notebook of Sand

• Recent Publications
• Recent Projects
• Conferences & Speaking
"Comparing Spatial Hypertext Collections"
  ACM Hypertext '09
"Archiving and Sharing Your Tinderbox"
  Tinderbox Weekend London '09
"The Electronic Nature of Future Literatures"
  Literary Studies Now, Apr '09
"The World University Project"
  St. John's Col. Cambridge, Feb '09
"Ethical Explanations,"
  The New Knowledge Forge, Jun '08
Lecture, Cambridge University
  Tragedy in E-Lit, Nov '07
Hypertext '07: Tragedy in E-Lit
Host for Tinderbox Cambridge '07
Keynote: Dickinson State Uni Conf
Upper Midwest NCHC'07: Speaker
eNarrative 6: Creative Nonfiction
HT'05: "Philadelphia Fullerine"
  Nelson award winning paper
NCHC '05:
 Nurturing Independent Scholarship
Riddick Practicum:
  Building Meeting Good Will
NCHC '04:
  Philadelphia Fullerine
  Lecture on American Studies
WWW@10: Nonfiction on the Web
NCHC '03: Parliamentary Procedure
ELL '03 -- Gawain Superstar
• (a)Musing (ad)Dictions:

Ideas. Tools. Art. Build --not buy. What works, what doesn't. Enjoy new media and software aesthetics at Tekka.

Theodore Gray (The Magic Black Box)

Faith, Life, Art, Academics. Sermons from my family away from home: Eden Chapel!

My other home: The Cambridge Union Society (in 2007, I designed our [Fresher's Guide])

The Economist daily news analysis

Global Higher Ed blog

• Hypertext/Writing

Writing the Living Web

Chief Scientist of Eastgate Systems, hypertext expert Mark Bernstein. (Electronic) Literature, cooking, art, etc.

Fabulous game reviews at playthisthing.

• Stats

Chapter I: Born. Lived. Died.

There is a Chapter II.

Locale: Lancaster County Pa, USA

Lineage: Guatemala

Religion: My faith is the primary focus of my life, influencing each part of me. I have been forgiven, cleansed, and empowered by Jesus Christ. Without him, I am a very thoughtful, competent idiot. With him, I am all I need to be, all I could ever hope for. I oppose institutional religious stagnation, but getting together with others is a good idea. God is real. Jesus Christ is his Son, and the Bible is true. Faith is not human effort. It's human choice. I try to be the most listening, understanding, and generous person I can.

Interests: Anything I can learn. Training and experience in new media, computer science, anglophone literature, education, parliamentary debate, democratic procedure, sculpture, and trumpet performance. Next: applied & computational linguistics, probably.

Education: Private school K-3. Home educated 4-12. Graduated Summa Cum Laude from Elizabethtown College in Jan 2006. As the 2006 Davies-Jackson Scholar, I studied English at St. John's College, Cambridge University from 2006 - 2008.

Memberships: Eden Baptist, Cambridge Union Society, ACM, AIP, GPA.

Alum of the Elizabethtown College Honors Program, sponsored by the Hershey Company.

Collaboration with Tinderbox
Monday, 20 Jul 2009 :-:

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.

GitX Shows Border, Color Changes: GitX & Tinderbox

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:

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
Adding and Annotating a Picture: Tinderbox & Git