<howto>

Developers wanting to participate in the collaborative meetings known as "Forrest Tuesday". Users interested in what goes on at these events.

<warning> This is a document written whilst testing the Gobby software. It is included here for reference only. Gobby is not currently the preferred choice of communication media for Forrest Tuesdays, we still use IRC at this time. </warning>

On the first Tuesday of each month we have a 24-hour get-together using the dev mailing list, Internet Relay Chat (IRC), and other collaborative tools, to work on Forrest development and get to know each other.

We exploring the use of a Gobby, a collaborative editor, to assist in focused development tasks. This HowTo will show you how.

ForrestTuesday starts at 06:00 UTC (6am Greenwich Mean Time in London) and lasts for 24 hours.

You will not need anything more than knowledge of how to install software on your computer. You will also need an Internet connection to participate in the meetings.

What is Gobby?

From the Gobby web site:

Gobby is a free collaborative editor based on libobby, a library which provides synced document buffers. It supports multiple documents in one session and a multi-user chat. It runs on Microsoft Windows, Mac OS X, Linux and other Unix-like platforms.

You can see some of its features. People interested in the technical details of how Gobby works should read this document.

Installing Required Software

Download Gooby from Gobby's web site (http://gobby.0x539.de/download.html). If you use one of the popular Linux distributions, chances are that Gobby is already available as a binary package for you. Debian/Ubuntu users, for instance, can simply `apt-get install gobby`.

Creating a Collaborative Session

When you first fire up Gobby, you will be presented with a blank screen with a toolbar on the top. Click on "Create Session" to host a session. If you need to join an existing session, click "Join session" instead.

To create a session, you need a computer connected to the Internet and you need to know its IP address. On Linux, this can be obtained with a `ifconfig -a`. On windows, try doing `ipcongfig /all`. For most cases, leaving the port values at default should be sufficient. Once you have specified the IP address and the name of the session, click "Create".

There is an early version of a server available for Gobby. This allows you to run a (semi-)permanent server. It is currently only available for linux.

Participating in a Forrest Tuesday event
Logging in to the session

To join a Gobby session, click on "Join session" on the toolbar. You will need to know the IP address of the machine the session is being hosted at. In the "Name" field, just put in your name. Choose a color (which you can change later) and click OK. You will then be prompted for the session password before joining.

When you first enter the Gobby session, if a document is already open, you will be informed the document exists but that you are not currently subscribed to it. There will be a "Subscribe" button below this notice that will give you access to the document once clicked. Documents that are created or opened during the session will also need to be subscribed to in a similar manner.

Using Chat for Discussion

Gobby has a chat session at the bottom of the window. This can be used to discuss what needs to be done and who is going to be doing it. Here is an (edited) chat session log from when this document was written.

Using Gobby for Collaborative Authoring

Gobby uses colors to identify the edits being done by participants. In order to make it easier to follow whats going on, its a good idea to choose visibly distinct colors. While joining a session, if you choose a color thats already in use by someone else, Gobby will refuse to connect to the session. Just choose some color that gets you in, because you can always change your color later on while a session is in progress (see "Set Color" under the "User" menu item).

<warning> If you close a document it closes for everyone, and remote users are not given the option to save any changes. So think carefully before closing anything. Generally speaking you should not close a document without asking all participants first. </warning>
Wrapping up
Closing the Session

To close, or leave a session, simply click on the "Quit Session" button in the toolbar. Be sure to save the files before doing so, especially if you "own" the file.

Note that the host must be careful not to quit the session until all participants ahve finished their work. It is a good idea to use chat to ensure everyone is done, alternatively, you could leave the session open until everyone else has quit.

<warning> With the current version of Gobby (0.2.2) if any user leaves a session the document is closed in all remaining users sessions. Any unsaved changes are lost. Do not leave a session without agreeing to do so with all other participants. </warning>
Recording the logs <note> At this point, we're not very sure if Gobby stores the chat logs somewhere on disk (we were not able to locate them). If you know the location of the logs, please let us know. </note>
Committing Documents to SVN

Any user can save a copy of a file being edited locally. However, it is recomended that someone be nominated as the person responsible for committing the file to SVN at the end of the session.

As mentioned before, the person responsible for committing should make sure that the document is properly formatted before committing.

Frequently Asked Questions General issues <question>What is the difference between a How-To and a tutorial?</question> <answer>

The goal of a How-To is to help the reader to accomplish a specific task with clear and consise instructions. While tutorials may contain How-To-like instructions and content, they also include additional background and conceptual content to help teach their readers higher order concepts along the way. How-Tos are concerned about filling an immediate, short-term need. Tutorials often provide long-term knowledge which can be applied across a range of needs.

</answer> Style issues <question>What coding convention should I follow?</question> <answer>

Gobby is a good collaborative editor, but not a very good editor. It allows minimalistic configuration flexibility for editing. For Gobby sessions, it is sufficient to choose a convention and stick with it. For instance, using 4 spaces for a tab indent, and using spaces to fill up the tabs -- this can be done through the "Preferences" item under the "Edit" menu.

The nominated committer should make sure that the document is properly formatted before committing to SVN.

<note> The current version of Gobby is 0.2.2, hopefully the editor will improve. </note> </answer> <question>What spelling convention should I follow?</question> <answer>

Use whatever spelling convention (American, British, etc.) that is most intuitive to you.

</answer>
Collaborative Note Taking

JotLive is a nice little web-app for taking notes collaboratively. Its almost like Gobby (each user has a different color, you can see the edits in real time), except that its web based. From the same folks who did Jotspot.

Editing Tips
Is Anyone Editing?

A quick way to see if someone is currently working on a document is to look at the revision number in the status bar. This number will increase by one with each keypress.

Chat Tips
History

The text entry widget (where you type for chat) can show you an editable history of your previous entries by hitting the up arrow on your keyboard. This functions much like the up arrow key in a Linux terminal.

</howto>