CommonScribe User Guide

Quick Start

Step 1. Log the Meeting

It is essential that someone keep a log of the chat session. The easiest way to do this (for W3C IRC sessions) is to issue these IRC commands:

/invite rrsagent
rrsagent, make records public

Failing this, many chat clients keep their own logs which can be converted into a suitable format.

Step 2. Type What is Happening (Using Scribe Conventions)

In general, CommonScribe pays attention to lines of the form "word: some text", and requires that the word either be a CommonScribe command or name a meeting participant. "name" in this context usually means the chatlog nickname. There are a few exceptions, though. (Hint: on most IRC clients one can use the tab character to expand among the nicknames.)

Scribe Activity IRC syntax Example
Declare who is scribing Scribe: <your name> Scribe: alanr
Recording what someone says <name>: <text of what they said> Sandro: I don't think that's a good idea
Shortcut for more from the same speaker ... <additional text> ... because it will never work
Correcting mistakes s/<old text>/<new text>/ s/it will/it would/
Setting topic for part of meeting Topic: <title of new topic> Topic: How to Scribe Effectively

(If Zakim is used to manage the agenda, and is reporting lines like "agendum 7. How to Chair Effectively", CommonScribe treats those lines as if they were Topic: lines.)

Setting a sub-topic for part of meeting subtopic: <title of new sub-topic> subtopic: Learning What Is Worth Writing Down
Record proposals

(some chairs prefer to do this themselves)

PROPOSED: <proposal text> PROPOSED: Our June meeting will be in San Francisco.

(after voting; some chairs prefer to do this themselves)

RESOLVED: <proposal text reiterated> RESOLVED: Our June meeting will be in San Francisco.

Step 3. Review the minutes

The meeting minutes appear automatically under https://www.w3.org/2013/meeting/YOUR_IRC_CHANNEL_NAME/YYYY-MM-DD. For example, if your group used the irc channel #dpub, the meeting for August 20, 2013, will be at https://www.w3.org/2013/meeting/dpub/2013-08-20. The URI https://www.w3.org/2013/meeting/YOUR_IRC_CHANNEL lists all the meeting records that have been created by CommonScribe.

Do NOT edit these files directly, nor should you try to access/modify them through CVS. These files are generated through the CommonScribe system. If you need to clean up the minutes, you have to do it by cleaning up the chat log (see below).

Step 4. Clean up and save the chat log

The minutes may show "scribe errors" or places where the minutes should be improved. You can do that by clicking on the “edit” link on the upper right hand corner of the page. This will lead you to an edit panel where the chat log can be modified and resubmitted; the results should be seen immediately.

You may want to put a line like this near the top of your chatlog like this:

<betty> present: betty, joe, jim, mary_smith, mary_jones

You can get a first approximation of that list of people by using the "Seen" line at the top of the formatting minutes, which is the list of everyone who said something on IRC or who the scribe mentioned. See People and Names for more details. Note that this command should be used for participants at meeting who are formally registered as part of your group, and not for guests (see below for the registration of guests).

Use these scribe commands as necessary to improve the output.

Scribe Activity IRC syntax Example
Provide a summary of the current (sub)topic (often added after-the-fact) summary: <text of summary> summary: Four proposals were considered, but none had consensus
Setting Sub-Sub-Topic Subsubtopic: <title of new sub-sub-topic> subsubtopic: Importance of good desert menu
Recording Attendance Present: <list of people of the group who are present> present: sandro, ian, evan, bijan
Recording Remote Attendance (for F2F meetings) Remote: <list of people attending remotely> remote: dave, deborah
Recording Guests (one person per line) Guest: <firstname> (<nickname>) <lastname>, <affiliation> guest: Manu Sporny
guest: Tim (timbl) Berners-Lee, W3C
Recording Regrets Regrets: <list of people unable to attend> regrets: frank, jim
Recording Chair Chair: <list of people chairing the meeting> chair: Ian

Some useful tips and tricks:

People and Names

Name References (namerefs)

In the chatlog, a nameref is a one-word name for a person. It is often their first name or a nickname, and it must match exactly one person.

When matching names, CommonScribe uses different lists of people, depending on the context. It uses the group-participants list in a W3C database for the attendance commands and for recognizing the author of a chat message, but for other commands it first tries to use the list of current-attendees. (The best way to modify that list and the corresponding chat nicknames is through the group's tracker: go to the 'Users' menu item of the right-hand menu of tracker).

If attendance is taken at a meeting (that is, if the PRESENT command is used at some point during the meeting), then matching stops there. Otherwise, when a nameref does not match any of the current-attendees, the list of group-participants is also searched. If a match is found there, it is used, and the person is deemed to be present. This builds an implicit attendance list of everyone who sends a chat message or is mentioned in a scribe command, which may be sufficient for some groups, obviating the need to take attendance.

The two stage name matching behavior is designed to allow convenient namerefs whenever possible. A typical case is where the group has multiple people with the same first name. At meetings where only one of them is in attendance, that first name can be used unambiguously, after attendance is taken. If name matching becomes too confusing, people should just use unique nicknames.

Note that name matching first looks at the nicknames. If an exact match is found with a nickname, no more names are looked at, and the name is deemed unambiguous. This means if a group has two people named Ivan, if there is agreement that one will be called Ivan and the other called something else, a seemingly-redundant nickname of "Ivan" should be entered (see the "Users" link in your groups tracker instance) for the one who will be known as "Ivan".

If no nickname match is found, CommonScribe tries to match using a set of rules like:

About CommonScribe, by Sandro Hawke, W3C
$Id: manual.html,v 1.23 2013-08-26 15:30:29 ivan Exp $