<scribe> ScribeNick: fantasai

Spec Writing Ecosystem:

* style

*pubrules

*tooling

<ernesto_jimenez> Ernesto Jimenez, Vodafone

<betehess> Alexandre Bertails, W3C, previous webmaster

<gkellogg_> Gregg Kellogg, RDFa, JSON-LD, ...

<arronei> Arron Eicholz, Microsoft

Elika Etemad aka fantasai, edit CSS specs

<eliot> Eliot Graff, Microsoft. Edit polyglot and IndexedDB specs

<ted_mobile> Ted Guild W3C Systems Team

<tmichel> thierry michel W3C

* boilerplate

*rich specs

<dom> http://lists.w3.org/Archives/Public/spec-prod/

Agenda creation

Tooling

robin: Topic is this big (very big)

dom: Find things not easily addressed today with tools we have

<dom> http://specifiction.com/

robin: Go to specifiction.com
... The idea is to have a simple interface for updating bibliographic data
... gives you proper thing to insert into your spec
... not ready for production
... send me feedback

bryan: What about ppl using wikis for specs?

<dom> (3 specs use the word specifiction http://www.google.com/search?hl=en&hs=y6P&channel=fs&q=%22specifiction%22+inurl%3ATR+site%3Awww.w3.org&oq=%22specifiction%22+inurl%3ATR+site%3Awww.w3.org&aq=f&aqi=&aql=1&gs_sm=e)

plh: Works for some groups. They run a script to generate spec

dom: W3C maintains ...

robin: One problem is it only does W3C documents
... Two it doesn't list editors in order, so you don't get right results

dom: That probably needs fixing

robin: Lots of work to update

<dom> http://www.w3.org/2004/07/references-checker-ui

<dom> http://www.w3.org/2007/05/ietf-references-checker

plh: Would be nice to have W3C docs and IETF docs [..] to check if references are out of date

robin: Do people edit on wikis because of wikis, or bccvs really sucks?

bryan: Want easy markup that publishes instantly

karl: wikis are convenient, but poor at expressing semantics in the spec

robin: One idea is to make wysywg version of respec

dom: some groups use a tool that takes a number of wiki tables and makes a publishable TR document
... So we have a tool that does this. Sandro was complaining he doesn't want to maintain it

??: I vote for wysywg spec editor

??: I need more semantics than available in MediaWiki

??: One barrier I've seen in other groups, that brings them back to word, is the wysywg editor

??: editing HTML isn't easy for that.

robin: w3c tools development is underfunded

ted: Part of problem is we have a lot of pl who are entrenched in their practices
... If we try to come to commo tool, will be very difficult
... if we can come up with common output that they can all produce, that ppl have to adhere to
... spec for spec output that can be fed into publication process
... There might be some ppl that won't produce the additional data we want without ..

??: .. semantics, address as part of a tool chain

vhardy: Could you converge on a set of tools going forward?

ted: get editors that are old-school, edit in vi

alexandre: people refuse, they just wnat to continue what they're doing

??: It's not the tool that matters but the output

??: Just ensure that spec has enough information to transform into reSpec

alexandre: if you say rdfa, not going to happen in HTMLWG

??: If we feel semantic markup is important...

fantasai: use microformats

ted: since diff editors have different practices in place, if we can have formal output they have to produce
... part of this is also the amount of data that is in pubrules checking
... that should be separate and added during the publication process

fantasai: In csswg we have macros that insert all the boilerplate junk

bryan: I like ppl that people focus on text, on content, rather than candy. Wiki is an easy place to get text in
... Could use as a tool in the editing process

robin: We're not looking at consolidating tools, but have common output

alexandre: intermediate language?

robin: Yes, HTML with some additions

karl: The freedom in editing is a good feature in W3C. Creates some problems, but a good thing.
... What's missing is the final output
... that is rich enough at the end that will make spec usable in different type of context.
... What tools can improve is, there is direct benefit to using more formal markup
... Tools can give you formal references, autogenerate status, ties to issues and bugs
... Give ppl useful tool for producing specs, then you will have adoption

robin: It's worth a shot.
... Let's move on to next topic
... these are useful things, will try to summarize what we've said and bring to spec-prod

Pubrules and boilerplate

dom: shouldn't have boilerplate

fantasai: boilerplate can be useful. Need place to send feedback, status of document, at the top. But legal disclaimers and here is link to all technical reports not related to my spec, not needed at the top

dom: One consideration is that as soon as we change pubrules, all editors have to change their toolchain
... Someone has to make a concrete proposal, iterate with editors to create a concrete proposal

vhardy: ... propose alternate design for the specs, styling is one part
... People ask for some interactivity for it. E.g. collapse some sections
... Don't have an answer, but we're looking at that and see if we can instrument that
... Idea for Status and Feedback, style so it's more prominent

plh: Some specs will put this info in the header

vhardy: I thikn status is a really big one, it's so confusing for most people to understand
... Having iconography that shows the status, this is not done

robin: and having links to an explanation

vhardy: Simple icon, simple label

plh: If you go to HTML spec, it says "don't look at this one, look at editor's draft"

fantasai: How about the csswg ppl take an action item to create a proposal

robin: wrt transition, could have pubrules and pubrules2

plh: pubrules is costly to maintain

robin: I wrote patch for it once, took ages to figure it out

plh: ten years old mess
... Coming up with pubrules2 will take time

ted: If we have common format, and all metadata added after
... we have more data bits per spec
... when comes time to produce it, all other stuff can be generated
... pubrules2 can trust database, instead of checking everything
... I imagine some people will want choices XHTML, HTML5, whatever

plh: Didn't hear anyone saying pubrules should go away

fantasai: think what pubrules checks for is reasonable, given the format that we're requiring right now

plh: Talking with IanJ, who created current pubrules
... He said we can do a lot of things, e.g. impose link-checking only at REC phase

fantasai: I think requiring drafts on w3.org to be valid HTML is a good idea...

discussion of link checker

fantasai: runnng link checker catches lots of errors for me

robin: problem with link checker is slow
... Only reason it's painful is it takes 15 minutes

???: Are we ok with using HTML5 on the website

<karl> http://search.cpan.org/dist/W3C-LinkChecker/

plh: we are very close, problem is getting pubrules to accept it
... We will have some guidelines.

<karl> http://dvcs.w3.org/hg/link-checker/

plh: e.g. should we allow things that we know are a bit unstable
... will be able to accept ?, <section>

robin: JS shim for IE6?

plh: No, we won't write a checker for that. Just require ppl to ensure their document will work in all browsers, bc we can't check your JavaScript

ACTION fantasai and vhardy: create concrete proposal for a new and better spec template for W3C

rich semantics

robin: two things -- how and what

?: Not sure we can agree on format

robin: If we can pick two, and standardize, that should be enough

alexandre: I would like to require fragment URLs to point to specific features and other things to test

fantasai: Everyone has section headers. If your sections are granular enough, you can at least link to those. Can go more granular

plh: CSSWG should share wisdom of link tests from specs

<scribe> ACTION: fantasai to start best practices doc for editing specs [recorded in http://www.w3.org/2011/11/02-pubs-minutes.html#action01]

fantasai: We link to fragment ids, just like alexandres said. Currently using section headings only.
... No special format for ids, except not auto-generated and not section numbers so can be stable

<karl> For spec organization and quality http://www.w3.org/TR/qaframe-spec/

<eliot> Thank you Karl

<dom> See http://www.w3.org/TR/test-methodology/ re marking up testable assertions or conformance requiremetns

Murray: Each clause with a MUST should have a span around that clause

robin: I agree with that, but getting editors to do that esp. manually is likely not to fly

Murray: I suggest to W3C that you need a Managing Editor. W3C is a publishing company, but you need someone who can take over all responsibility and manage all publishing. Not only system, but content. Someone people can turn to for guidance.

plh: IanJ was playing that role in the past

dom: Key is W3C products is documents, so we should have someone managing that

robin: In reSpec generated docs, each RFC2119 word is marked

dom: If you can identify your conformance requirements, makes it more testable.

robin: everyone should read dom's document

Murray: Sounds like the links are tested periodically

robin: at every publication

Murray: When I worked at SEO, we transformed all our documents. Ran through everything, then sent an email with link in it, for the author or editor responsible to say which links are broken
... Motivated ppl to fix them b/c annoying

plh: Could run it over editor's draft

dom: Could make it optional.

Murray: You can put the pain earlier or later

dom: It's not just early you're proposing or often

Murray: Really worked for us. First iew weeks really hard, but after that ok

This is scribe.perl Revision: 1.136  of Date: 2011/05/12 12:01:43  
Check for newer version at http://dev.w3.org/cvsweb/~checkout~/2002/scribe/

Guessing input format: RRSAgent_Text_Format (score 1.00)

Succeeded: s/robin/dom/
Succeeded: s/?/karl/
Succeeded: s/HTML editor/editing HTML/
Succeeded: s/ties to .../ties to issues and bugs/
Succeeded: s/full URIs/fragment URLs/
Succeeded: s/???/Murray/
Found ScribeNick: fantasai
Inferring Scribes: fantasai
Present: betehess Dominique_Hazael-Massieux_W3C Bryan_Sullivan

WARNING: No meeting title found!
You should specify the meeting title like this:
<dbooth> Meeting: Weekly Baking Club Meeting


WARNING: No meeting chair found!
You should specify the meeting chair like this:
<dbooth> Chair: dbooth

Got date from IRC log name: 02 Nov 2011
Guessing minutes URL: http://www.w3.org/2011/11/02-pubs-minutes.html
People with action items: fantasai

WARNING: Input appears to use implicit continuation lines.
You may need the "-implicitContinuations" option.