Chair Training Module 2: Tools

24 Apr 2014

See also: IRC log, Audio recording



Ralph Swick, Jeff Jaffe, Joshue O Connor, Lisa Seeman, Scott Peterson, Shawn Henry, Andy Coleman, Vlad Levantovsky, Arnaud Le Hors, Giri Mandyam, Andrew Kirkpatrick, Christine Runnegar, Steve Zilles, Wendy Seltzer, Daniel Veditz, Yosuke Funahashi, Sharron Rush, Jim Allan, Nigel Megitt
wseltzer, dveditz


<Ralph> [gold stars for the five who arrived on time]

-> Tools for W3C Groups

Ralph: This session is part 2 of a 4-part series
... training for W3C group chairs
... Next 2 sessions will cover facilitation topics


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.


Ralph: every categorization scheme needs a miscellaneous topic. Hence, "other tasks"
... I'll try to listen to questions, will likely defer response


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.


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.


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


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.


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.


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

-> Predefined ACLs

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.


-> W3C Editors' Home Page

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


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

-> ReSpec template


Ralph: link checker, allows recursion
... ,checklink


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


Ralph: pubrules checks for required header material


Ralph: tools for managing discussion
... primary tools: tracker, bugzilla, lc comments tracker


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


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

Ralph: ",minutes", pretty print text ",text", ",validate" runs the validator
... ",pubrules",
... ",pubruleserrors" shows the errors generated
... mailing list link for more questions on these 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

Arnaud: I find the last call tracker tool hard to use
... hard to remember the arcane details

<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
[End of minutes]

Minutes formatted by David Booth's scribe.perl version 1.138 (CVS log)
$Date: 2014-07-14 20:14:02 $