XML Security WG Scribe-Instructions Page

Frederick Hirsch

Introduction

This page summarizes intructions for scribing and IRC participation. It is based on other instructions, in particular WS-Addressing minute instructions and WS-Policy scribe instructions. Edited section on Actions from WSC instructions and added information on tracking messages related to actions.

prepare | irc setup | common tasks | scribing (discussion, actions, resolutions) | concluding | follow-up | more information

The advice here is geared towards taking minutes for a distributed meeting using the W3C tools in IRC. However, much is applicable to face-to-face meetings and minutes taken with other tools (e.g., as text).

Prepare

1. Determine conference channel

   Teleconference Calendar

   In the case of XML Security WG the channel is #xmlsec. In the following, replace "[channel]" with #xmlsec.

Setup IRC session

At the start of the meeting it is necessary to setup the agent that manages minutes (RRSAgent) as well as the voice bridge (Zakim). The easiest way to do this is to use trackbot-ng from within the IRC chat as follows:

trackbot-ng, start telcon

This should include these manual commands (the /invite commands should not be executed using /me):

1. /invite Zakim [channel] -- e.g., /invite Zakim #xmlsec
2. /invite RRSAgent [channel] -- e.g., /invite RRSAgent #xmlsec
3. RRSAgent, make log member --make the log member visible.
4. Zakim, this will be [conference name] -- e.g., "Zakim, this will be XMLSEC"
5. Meeting: [name] -- e.g., "Meeting: XML Security WG Teleconference"
6. Date: [date] -- e.g., "Date: 05 February 2008"

In addition, it is necessary to enter the following commands manually in IRC:

1. Chair: [chair's name]-- e.g., "Chair: Frederick Hirsch"
2. Scribe: [full name] or ScribeNick: [IRC handle]
3. Agenda: [URI] -- a link to the meeting's agenda

Note that trackbot-ng may be configured differently by each W3C Working Group. What is documented here corresponds to the current XML Security Group configuration.

Common tasks during session

1. Determine who is on the phone and IRC channel

   Zakim, who is here?

2. Enter text into the chat which will not appear in the minutes

   /me [some text]

   This can be useful for RRSAgent questions, for example.

3. Establish identity of any unknown Zakim callers

   /me zakim, ??p9 is me

   /me zakim, ??p9 is [handle]

4. Get the code for the call

   /me zakim, what is the code?

5. Send a private IRC message to a participant in the IRC channel.

   /msg [nickname] [some text]

6. Correct errors using ed expressions

   s/bad text/good text/

7. Get in the queue

   q+

   or

   q+ to remember something
   (In this case, upon ack, "remember something" will be shown. Note that the to is required here.

Scribe tasks

Capture discussions

1. Record start of discussion of agenda topic

   TOPIC: [topic name]

   It is better to record more topics (e.g. for major and minor agenda items) than not to, so use TOPIC: freely.

2. Record discussion by participants, using IRC handle to identify participant.

   Be sure to avoid relying on surrounding discussion and other context, because action items and resolutions are usually read without the rest of the minutes. e.g., don't say "Joe should do this by tomorrow"; say "Joe should make a proposal about the Widget Model by 2004-12-09."

   [handle]: [comments] -- e.g., "Joe: I think we should use TLS 2.0"

   More than one line can be captured using ... instead of handle:

   ... [continued comments] -- e.g., "... and not SSL 1.0"

3. Announcements

   Be sure to capture any important announcements about deadlines, meeting dates, etc.

Record Actions

Minuting action items clearly is critical. An action item is a promise given in front of the group to do a certain task by a certain time. (Which might need to be renegotiated.)

Therefore, an action item has:

• a responsible person
• a task description which needs to be understandable without the context of the minutes. Therefore, "to do the same", "to review the document" and the like are not appropriate action items.
• a due date

If an action item is negotiated, it is at times useful for the chair or the scribe to drop a proposed action wording into IRC before feeding the action item into tracker.

When action item negotiations are finished, the action item is minuted on IRC:

ACTION: somebody to do something [ - due YYYY-MM-DD ]

If no due date is given, the default are 7 days.

somebody is usually the first name or last name; note, however, that tracker might not be able to (uniquely) resolve certain acronyms or names. In that case, you might have an exchange like this one:

<tlr> ACTION: rachna to do nothing
<trackbot> Sorry, amibiguous username (more than one match) - rachna
<trackbot> Try using a different identifier, such as family name or username (eg. rdhamija2, rdhamija)

Note how, in this case, trackbot actually gives you identifiers to work with -- in this particular case, use rdhamija2.

In general it is best to use the w3c user login, for this reason it may be useful to use this as your IRC handle.

<tlr> ACTION: w3c-login to do something.

The responsibility here is to check that trackbot actually returns an action identifier:

<tlr> ACTION: thomas to update due dates
<trackbot> Created ACTION-207 - Update due dates [on Thomas Roessler - due 2007-05-03]

Note that to conclude an action, you should send an email to the mail list regarding the resolution. You should include the string "ACTION-nnn" in the body of the message, where nnn corresponds to the message number (e.g. ACTION-207). This will cause Tracker to automatically place a link to the message into the record of the action, making it easier to subsequently understand what happened (e.g. why it was closed).

Record Working Group decisions (resolutions)

It is essential to capture working group decisions and consensus in the minutes. This enables the working group to move forward without revisiting previous decisions. It also enables an audit trail so it is possible to understand when and how decisions were made. If discussion is captured well this enables understanding of consensus.

Before recording a resolution, enter the draft text into the IRC so the WG can agree on the wording. Once this is agreed upon, the resolution can be formally entered using RRSAgent by typing the following:

RESOLUTION: [precisely worded text] -- e.g., RESOLUTION: The location of the November F2F is agreed to be Cambridge, MA

After every resolution, create a URI that notes the location by asking RRSAgent for the location:

RRSAgent, where am I?

RRSAgent should respond by creating a URI and entering it into the minutes, enabling others to create links to the resolution.

Example:

RESOLUTION: 4477 closed with http://lists.w3.org/Archives/Public/public-ws-policy/2007Apr/0077.html
17:00:31 [person]
rrsagent, where am i?
17:00:31 [RRSAgent]
See http://www.w3.org/2007/04/25-ws-policy-irc#T17-00-31

Note that this appears in the IRC Log, not necessarily the finished minutes.

Concluding the Meeting

1. Zakim, list participants
2. RRSAgent, make log member -- make the log member.
3. RRSAgent, generate minutes
4. Zakim, bye -- hang up bridge
5. RRSAgent, bye

RRSAgent generates minutes, which then may need some minor HTML cleanup.

1. The scribe may do this and then send the result to the team contact (or the team contact may do it directly.)
2. The team contact will post the minutes to the mailing list for review.
3. Once approved at a WG meeting, the team contact will edit the minutes (remove Draft), set the correct access permissions and post.

Note that it is always possible to get a text only version of the minutes by using the URL for the HTML version and adding ",text" at the end, e.g. "http://www.w3.org/2007/04/17-xmlsec-minutes,text".

Follow up after the Meeting

The scribe should take the HTML minutes produced at the URL produced in response to "RRSagent, generate minutes", clean the HTML up by hand. Please do this in a tool that does not add unnecessary markup, scripting etc. Emacs might be a good choice.

Clean up should include the following:

1. Check and correct list of participants, regrets, chair and scribe information. Remove phone numbers, fix names.
2. Correct typos and remove duplicated material
3. Run the file through a spelling checker.
4. Remove processing notes at end (Scribe.perl diagnostic output)
5. Make sure it is Valid HTML (In emacs you can use nxml mode.)
6. and, most importantly, reviewing the content to see it makes sense, and adjusting to fit what was said.

Please send the revised minutes as an email attachment in a message to the members-only list.

For More Information

• W3C IRC documentation
• IRC Trackbot
• Zakim agent's documentation
• RRSAgent documentation
• Scribe.pl script

Copyright © 2006-2007 W3C^® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply. Your interactions with this site are in accordance with our public and Member privacy statements.