See also: IRC log, Audio recording
Related:
<Ralph> [gold stars for the five who arrived on time]
Ralph: This session is part 2 of a 4-part
series
... training for W3C group chairs
... Next 2 sessions will cover facilitation topics
[slide2]
Ralph: This session is being recorded.
... Slides are publicly accessible; we expect to make the minutes
available.
... Also audio, if of sufficient quality. Transcript, someday.
[slide3]
Ralph: every categorization scheme needs a
miscellaneous topic. Hence, "other tasks"
... I'll try to listen to questions, will likely defer response
[slide4]
Ralph: Use your favorite text-editing or
markup-editing tool
... many new team members use BlueGriffon
... but any markup editor of your/your document editor's choice is fine
with us.
... How to get content onto the W3C site? several ways.
... We support WebDAV
... The entire W3C website (minus wikis and blogs) is maintained in CVS
... Direct HTTP write access
... We support Mercurial repos, git
... Access control supports all the previous items.
... Amaya, mentioned for historical reasons. Web browser that supported
editing.
... Unfortunately, it is no longer actively maintained.
[slide5]
Ralph: WebDAV, linked a guide, invite
updates.
... One feature of WebDAV in many OSes is a standard file-system view
... Take care. It's folder-oriented and easy to delete what you want or
don't mean to delete.
... Save-as looks like local.
... Most general and simplest format for arbirtrary text markup editors.
[slide6]
Ralph: CVS is what we use. Other things are interfaces on top of CVS store
-> CVS at W3C
Ralph: conceptual differences between git and cvs are small, though UI differences are larger
[slide7]
Ralph: HTTP PUT has been specified since day
0.
... edit.w3.org is the service that provides HTTP PUT
... I go through this in detail because one of your responsibilities as
a chair is to provide and maintain group homepages, with information
about what your group is doing.
[slide8]
Ralph: As CVS was aging, we looked around,
and at that time, Mercurial (hg) was nominated.
... dvcs.w3.org is our w3c-hosted hg instance
... We expect to provide persistence for the mercurial store as we do
for the rest of our site
... Developers who are both writing code and participating as editors
will tend to have tool preferences
... We're still working on how best to integrate git and github
... with the w3.org site.
[slide9]
Ralph: Underlying fine-grained access
control mechanism
... Unlike many webservers, where ACLs are per-directory, W3C site has
per-resource ACLs
... "Date space" (whether fondly or less fondly called) /YYYY/MM/
... all under fine-grained access-control
... Allows us to create a working group home under date space
... with write-access to any appropriate member of your WG
... you as chairs will have HTTP PUT access there
... If you've created a group area and provided access to editors,
there's also a tool allowing you to set default ACLs for new documents
there
Ralph: That was the general description of
how things get on the W3C website.
... Next, I'll talk more specifically about the technical report
production workflow.
[slide10]
Ralph: House style, not enforced except
through pubrules
... Markup of specs, tool of choice seems to be ReSpec
... Tools to help with document revision process: htmldiff: inline
annotation of html doc differences
... Services available on W3C site
... source is also available
... Spell checking; link-checking;
... Unicorn: markup validation tools.
... Pubrules checker is often-cursed
... but it's nonetheless important
[slide11]
Ralph: Respec.
... Puts in much of the boilerplate template
... As efforts to revise rec-track process or publishing format proceed,
... there may be more encouragement to use ReSpec
... I have heard strong suggestions that documents using ReSpec will be
more flexible
... and extensible, because ReSpec captures metadata
... Start from a template
[slide12]
Ralph: link checker, allows recursion
... ,checklink
[slide13]
Ralph: Unicorn, a multiple markup validator.
... a required step in spec publication pipeline, pubrules
... Validator Suite offers recursive testing
... but you will be validating pages as you create them
[slide14]
Ralph: pubrules checks for required header material
[slide15]
Ralph: tools for managing discussion
... primary tools: tracker, bugzilla, lc comments tracker
[slide16]
Ralph: We have a public bugzilla instance
... no requirement that you use bugzilla, but many find it useful, e.g.
HTML WG
... at major transition points, LC->CR, CR->PR, director will ask
for verification that your group has responded to comments
... if you're using bugzilla to track comments, these scripts will help
generate disposition of comments
... bugs2html bugzilla.xsl
[slide17]
Ralph: Last Call Comment Tracker, provides
means to track comments, annotate, and reply
... use of the particular tool is optional, but producing the report is
required
... Meeting management and record keeping
<scribe> scribenick: dveditz
tools: irc (e.g. this #chairing channel)
... Zakim, name refers to two separate services (HW conf bridge, IRC
agent)
... RRSAgent is the tool for recording meetings
... tracker is the tool for actions and issues
... WBS, scribe.perl (HTML formatted meeting notes)
tools: link to Scribe 101 -- an introduction
to how to run meetings and use these tools.
... last link is more information on using these tools
[slide 19]
Ralph: link to reserving a teleconference
slot (bridge physical capacity is limited)
... reserved via email messages, details at that link
... Zakim commands are documented, managing the speaker queue and agenda
can be done via zakim
... several styles these tools can be used, link to a document with
hints and kinks you might find yourself in. tricks on how to use Zakim
for specific situations
... (please feel free to add your own tips to the wiki page)
[slide 20]
Ralph: many groups find the parts of zakim that manage speaker tools can be useful apart from the teleconferencing bridge, invite Zakim into your channel
Ralph: RRSAgent can be invited into a
channel as well
... there's a timelag for RRSAgent, but if it's more than 2-3 minutes
it's probably stuck. send a trouble report
... both zakim and rrsagent need to be invited into your specific
channel
... /invite rrsagent #chairing for example
[slide 21]
Ralph: tracker
... has a config db and knows about regular channels and meetings
... it will invite zakim and rrsagent for you and set up the mtg record
... and format the meeting notes later
... real use is to manage a db of action items, your group's issues, and
track resolutions
... tracker itself is the latest in several variations on the same theme
... tracker has been designed and tuned for the w3c community style
... 3 interfaces
... (links) trackbot irc interface (not present in this specific
channel, but you're welcome to ask the systems team to set it up for
your channel)
... web interface to the tracker -- superset of the IRC interface
... and an email interface to your WG's mailing list
... tracker will identify msgs that refer to specific actions and
include those messages in with the history of that action
... depending on how good your group members are at including the magic
keywords in the messages
... best keeping messages about one issue in separate from messages
abouot other issues.
... if they're combined sometimes the same mail gets included into
multiple issue records
... traditionally tracker is configured to always be present on your
channel, very convenient to ask about specific issues
... when a mtg is in progress
... when using bugzilla or LC tracker there's a tool for creating the
Director's last call comments (record?)
... DisCo: that script expects a specific style of comments (link in
slide)
... if you use tracker to track your last call comments that's a fine
thing to do, but look at the documentation for DisCo so you know ahead
of time what style comment the tool is looking for
[slide 22]
Ralph: these 3 tools can be a source of
confusion for your members
... for some need to address the bot directly ("Zakim, <dothis>"
"trackbot, <dothis>)")
... zakim does teleconferencing management
... rrsagent is a record keeping function
... trackbot interfaces with the actions and issues database.
... rrsagent has some recognition of issues and actions, trackbot
recognizes the same things
[slide 23]
Ralph: web-based strawpoll info gathering
tool
... when creating a poll using WBS there are templates for common
situations: teleconferencing scheduling, meeting times,
... not a common place to find these
... any questionnaire you find where you like its style you can grab a
copy and adapt it to your needs
... link at top of slide 23
... to detailed documentation on WBS
[slide 24]
Ralph: last of the tools is scribe.perl
... nrmally you don't see this directly, bundled in with rrsagent
functionality usually
... link to editing commands to making corrections to what the scribe
has recorded
... scribe.perl can be invoked independently of rrsagent -- useful if
you need to generate minutes the day after the meeting (for example)
... rrsagent wouldn't know the correct date at that point
[slide 25]
Ralph: "Other"...
... needs it's own meeting: how do we test a specification. "Test the
Web Forward"
... repository hosted by W3C (thanks to Adobe for donating that to
us)
... contains a primer on getting started with git and github
... if your group is using that and have some members that are
unfamiliar with those tools
... comments or questions about the the testing workflow the
public-test-infra list is the best place
... we use MediaWiki to manage all our wikis (public, group, private)
... link to style hints and suggestions
... our blogging environment is Wordpress -- link to how to request a
blog for your WG if you want to use that
... link to Slidy, a presentation tool (used in this presentation, for
example)
... I like Slidy, the format is HTML and that's a familiar environment
for many
[slide 26]
Ralph: more information available on the w3
tools wiki
... a little out of date, but still useful
... I mentioned earlier re link-checker that there was a shortcut
... add ",checklink" to end of URLs on w3.org
... there are other "comma" tools
[slide 27]
Ralph: thanks to all for the development of
the tools I've described here
... please let us know your own favorite ways to work with or around
these tools
... and we'll add the best to the guidebook and the tools wiki
<AWK> Agree re: comment tracker. The filtering mechanism is broken in unpredictable ways that make it difficult to rely on.
Arnaud: if you're looking for a tool that needs help I recommend this one
Ralph: what's your favorite tool that you've used for things like this?
Arnaud1: I've seen people use simple wiki
pages, pretty bare but easier to use
... the intention is good, but the implementation is not. If I had to do
it again I'd do it by hand because at least you know exactly what's
going on
Ralph: I'm hearing that you struggle with LC
tracker, and prefer to do it "by hand"
... I don't know when we'll have resources to revise any of these tools
<christine> Thanks, and apologies. I need to leave the call.
Arnaud1: the status is that this is not an
officially supported tool but .... LDP group used "CommonScribe"
... it will transform minutes into nicely formatted
comments
Ralph: thanks for mentioning CommonScribe...
Sandro's done a nice job with it
... most of these tools were developed by individuals trying to make a
repetitive task they had to do easier
... everyone of these tools started as a midnight hack by some
individual
... CommonScribe is a very useful tool, hasn't yet made the transition
from "Sandro's project" to officially supported by the Systems Team but
I agree it's a nice tool
... can't recommend it to other WG chairs who don't have the benefit of
Sandro in your group to fix things when it goes wrong
<Zakim> AWK, you wanted to ask who to notify about issues with tools
Arnaud1: It's a good tool but I also would not recommend it to groups without Sandro present
AWK: I like the tracker tool, we use it all
the time, but aspects we can't use
... when comments are sent to the list the tool offers the ability to
import from a URL but it never works. who do we talk to about that?
<Ralph> mailto:sysreq@w3.org for bugs
Ralph: if you're having difficulty with a
documented feature that doesn't work send mail to sysreq@w3.org
... I would characterize that as a bug and that's perfectly appropriate
<Ralph> mailto:w3t-sys@w3.org for feature requests
Ralph: feature requests can go to w3t-sys@w3.org
<Ralph> mailto:w3c-tools@w3.org for discussion
Ralph: for collaboration on tool development I recommend w3c-tools@w3.org I think that's an underutilized list for discussions about tools needs
<Arnaud1> irc channel #sysreq works well when looking for quick remedies - like some system down
Ralph: Arnaud1 commented in irc that there's also the #sysreq irc channel. no promises it's monitored 24/7 but it often is
Arnaud1: I will add that even if you join and it looks like no one's there, the sysreq team has tools and will be notified when you post something there
Ralph: thx for mentioning that. unlike most
channels you won't necessarily see people just sitting there. When you
type there it interrupts other channels the sysreq folks are watching
... like a paging system
... any other favorite tools you'd like to share?
... I perhaps disparaged by omission many tools that have been used in
the past or are still being used
... In this presentation I chose the tools that are most common and
current best practices
... but there are others that can be useful
... thanks for expressing your interest by attending
... stay safe out there with w3c tools, and please share your
experiences with us so we can improve tools and future chairs can
benefit from you
<Lisa_Seeman> [thanks to Ralph.. ]
Summary of Action Items