TalkBank Collaborative Commentary

Collaborative Commentary is a system to collaboratively code (tag) TalkBank transcripts.
Once you sign up for an account, join a group or make a new one.
Within a group, define a set of tags describing phenomenon you expect to find in transcripts. You and your fellow group members then use these tags to find and mark examples of them in TalkBank.
You can message other group members to resolve disagreements and continually refine your tags. As your group marks documents with tags, you can search by tag to find examples your group has found.
Your group collaboratively builds a searchable database across TalkBank transcripts. This database can be made readable to a select group of people, or be made open to the world.

1. Sign Up

1.1 Create an Account

Open the TalkBank Browser.
Click the "Collab" button in the top right corner. Select "New user".

Choose a password and enter your info (first/last name, ...).

Your email address will be your ID for collaborative commentary.

When you click "Submit", you will be sent an email link to click and verify your address.
After you click the link emailed to you, you will be able to log in and use collaborative commentary.
Click the "Collab" button in the top right corner and log in with your email and password.

1.2 Forgot/Reset Password

If you should forget your password or wish to reset it:

Click the "Collab" button in the top right corner.
Select "Forgot password?".

Enter your email address and a link will be sent to reset your password.

2. Groups

2.1 Create a Group

All tags are created within the context of a group. Each group has its own set of annotations for TalkBank documents.
Typically, you will join an existing group instead of creating a new one (see "Joining a Group" below). In that case, you can skip this step. But if you plan to be the manager of a new group then you should use the information here to create a new group.
To create a group, click the "Collab" button in the top right corner.
From the "Menu", select "Create New Group".

Choose a name for your group.
Choose a default permission level for new members of this group.

You can set this to "Read" for this example.
This means anybody can view your group's annotations, but need your permission to write them.

2.2 Joining a Group

If there is a group you want to join, you need to know the email address of the group's owner. Alternatively, you may have already been added to a group by the group manager.
Click the "Collab" button in the top right corner and from the "Menu" select "Request to Join Group".

Enter the email address of the group's owner and click "List available groups". Choose a group you wish to join and click "Request to join".

Now when you select "Participate in Group" from the menu, you'll be able to see this group under "Joined groups".

2.3 Managing Group Permissions

(If you don't plan to create and manage members in a group, you do not need to read this section.)
If you create a group, you set permissions to determine who is allowed to read and write annotations within it.
You define what users are allowed to do in groups you create by setting permissions in two ways:

Setting default permissions when any new user joins your group.
Then if necessary, modify permissions for current group members.

Click the "Collab" button in the top right corner and from the "Menu" select "Manage Permissions"

Select the group you wish to manage.
There are two blue bars that toggle when clicked, one to set permissions for current members, the other for future members:

Click the blue bar "Current Member Permissions":

Here you can set permissions for individual members who requested to join your group:

Write: Allow member to write annotations.
Read: Allow member to only read annotations.
None: Ban member from group (cannot read or write anything).

Selecting Permission to Author Tags allows the member to define the set of tags used by the group.

Click the blue bar "Future Member Permissions":

Here you can set permissions for members at the moment they join your group.
Under "Individual future member permissions" you set permissions for individual users you expect to join by addding their email addresses and choosing "Read" or "Write" permission

This is a convenience to override default permissions for specific members as soon as they join the group.
For example, a group with default "Read" only permissions, members cannot write until you grant them "Write" permission.
But by adding setting an individual's permission here to "Write", they can immediately start writing tags when they join (and not have to wait for you to change their permission to "Write"):

Under "Default future member permissions", you set general permissions for users when they join the group. Permissions you specify for an individual under "Individual future member permissions" override what you set here:

Note: Once a user joins a group, their permissions can be changed at any time under "Current Member Permissions".

3. Tags

3.1 What are tags and how are they useful?

Tags are defined terms written and shared by members of a group.
They are used to mark recurring events across transcripts.
Tags provide a shorthand and shared vocabulary for a group.
By marking transcripts with tags, the group creates a searchable database of interesting events (see the "Search by tags" section below).

3.2 Defining tag set.

To define new tags and see tags members have defined in the group, click the small tag icon in the top right corner.

This opens a window to view existing tags and (if given permission by the group owner) define new ones:

If you don't have permission to create tag definitions for a group, you will not see the "Import Tags" button or the "Create New Tags" button.
If you have permission by the group owner, you may create new tags, import them from other groups, and edit/delete existing tag definitions.

4. Annotate Transcripts

4.1 Choose group

Since all annotation is done within the context of a group, we first choose a group.
Click the "Collab" button in the top right corner.
From the "Menu", select "Participate in Group" and choose the group you wish to view and click "Participate":

Notice the small black tab at the top of the screen that appears indicating the group you're currently viewing:

You can now annotate any document in TalkBank with tags defined in this group.

4.2 Selecting utterances

To select utterance(s) to annotate:

Choose a document in TBB and select a range of utterances you wish to annotate by clicking start/end utterance numbers.
For example, click 2 and 5 to annotate utterances 2 through 5 (see below).
To annotate just one utterance, click the same number twice. For example, click 3 and 3 again only annotate utterance 3.

After submitting an annotation, a small "C" will appear to the left of the first utterance that annotation refers to.

To view annotations, click the "C" to the left of an utterance to view the annotation beginning at that utterance.

4.3 Annotate with tags

Once tags are defined, a pulldown of available tags appears when adding or editing an annotation. Select a tag and click the "TAG" button to attach a tag to the annotation.

To detach a tag, click the 'X' to the right of the tag name and click "Submit" to save your change.

4.4 Edit/Delete annotations

To edit or delete an annotation, click the small paper and pencil icon:

This will open a window to edit or delete the annotation:

4.5 Contact fellow collaborators

Click on a collaborator's name to send them a message about their annotation.

5. Search

To search collaborative commentary, click the magnifying glass icon in the top right corner.

5.1 Search by tags

From the "Find" menu, select "Tags" for a list of links to tags in documents. The listing is arranged by corpora (bank) then by tag name. After each link in parenthesis is the utterance range the tag describes.

5.2 Search for documents with annotations

From the "Find" menu, select "Annotated Documents" for a list of links to annotated documents. After each link in parenthesis is the number of annotations in that doc.

5.3 Search for annotations by user

From the "Find" menu, select "Annotations by User" for a list of links to annotations arranged by author name then by corpora (bank). After each link in parenthesis is the utterance range for that annotation.