See also: IRC log
<scribe> scribenick: karl
<scribe> scribe: karl dubost
doug scheppers, w3c
chris David Mills, Opera Software
Masataka Yakura, Mitsue Links
Yamada, Internet Academy
Hiroki Yamada, W3C fellow, Internet Academy
(working on documentation on w3c web sites)
Don Brutzman, 3D consortium
Eliott Graff, Editor lead for dev doc at Microsoft
Kimberley Blessing, Comcast
Arron Eicholz xxx, Microsoft
Yahuda Katz, Ruby On rails
Paul Irish, Google
Karl Dubost, Opera Software
Marie-Claire Forgues, W3C, Education group
Ernesto Jimenez, Vodafone
Char James-Tanny, participant in WAI EOWG
Cynthia Shelly, Microsoft, Accessible app development, HTML & PF WGs
Shawn Henry, W3C
Jennifer Sutton, participant in WAI EOWG
Hiroto Yahagi, W3C system team
Tobie Langel, Facebook
Sharon Russ, Nobility
chris: I chair the web education
... we want to provide a vendor neutral canonical source of documentation
chris: focused first on
... but also web designers, marketing
... the curriculum project has the aim to create a curriculum for University
... We would like to develop a certification effort for training
<shawn> s/Shane RTuss, Nobility/Sharron Rush Knowbility/
chris: We want to form an
... There are good universities, but the things which are taught are sometimes pretty bad
doug: We want the documentation
to be CC-BY
... so to have attributions, but make it possible for people to reuse it freely
... Each person would not have to start from scratch.
yehuda: about curriculum, most of the people being Web developers didn't learn at schools.
<marie> chris: all about pragmatism
yehuda: How do we get the words out to university once we have the curriculum.
doug: We have to stay pragmatism
kimberly: The information needs
to be made available
... if the schools are using it or not is secondary.
<marie> need to tap professionnals
kimberly: some schools are asking
me to teach in school.
... so it can be useful.
yehuda: You are a practitioner.
Kimberly: evangelists can use
... the students will be able to use it.
chris: We are trying to help
local educators, more than being perfect
... We also want international subgroups.
... there are passionate group of French and Japanese people involved in Web education Web standards
<marie> equivalent quality
chris: to have equivalent
qualities and not necessary exact translation.
... It is difficult to do for a local company.
doug: Having it done by local
... is a lot more effective.
... Hiro has made a lot of Web sites on the W3C site
... and he is translating to Japanese
<wycats> Yehuda, btw :)
doug: and finally to reach out Japanese developer community
kimberly: the Web standard
project has a lot of persons. We have a 100 individuals.
... We have already a lot of people in different languages
... This is a group of people we can reach out.
doug: I have been talking to
people I know already.
... but there are other people.
yehuda: some people are reading
... The HTML5 spec did a good job at it.
... JSfiddle did also a good job.
chris: better stylesheets, prose more readable in the specifications could be one of the goals.
murray: years ago, w3c wanted to
have technical writers
... but we kind of move away from that.
doug: We do not have that much money.
shawn: It's not a lack of interests.
<wycats> my two suggestions were: (a) a directive that W3C specs have a "developer mode" a la the HTML5 spec such that the spec can be used as documentation; (b) live documentation (a la jsfiddle) that show a feature actually working in real life and linked to the specs
cyns: I would like to see more
howto, step by step documentation
... and cases studies
doug: a bit like web standards sherpa.
cyns: working with them would be good
<paul_irish> karl was hired to help with readability of specs. it was very difficult to convince people to improve the readability of specs.
<paul_irish> w3c tried really hard to hire technical writers. it's difficult to get technical writers involved in the writing of specs. there are certain specs that are more appropriate for tech writer involvement.
<shawn> karl: in past was hired for QA, including improve readability, it was super hard to convince people to improve readability. we tried to recruit technical editors, and it was very hard for tech editors to [?be integrated into working group]. if had to choose between improving the spec, versus making support material for developers, I would do latter.
doug: I agree with both of you
... Work on getting documentation good.
... The people writing html5rocks try to reverse engineer what the editor meant
... There are usually huge thread about hidden editors
yehuda: the spec are already good. It would be good to improve them for webdevs
cyns: It was easy in the past
brutzman: The documentation they want for objects is how the object is working. hopefully 3D will become a first class object.
doug: we will not be able to
... so the community process will reflect what people want to do .
<marie> ... please write down on the wiki
Tobie: AppCache is done for one
thing, and they use it for something. There is a big
... in between what the spec is meant for
... and what the people are using it for
<marie> doug: that's why we need to improve use cases
tobie: we need also to know what
is implemented where
... something implemented nowhere
... is useless
doug: test suites can help achieve that
aaron: test suites provide two
levels of information
... is it implemented and the quality of implementation
doug: for svg the test suite becomes documentation.
<Zakim> karl, you wanted to ask about narratives of Web standards discussions
<marie> karl: difficult sometimes to understand what is in mailing lists. Would be good to have someone telling the "story"
<marie> ... kind of a summary
<marie> ... i'm now following webapps and html5 and it takes me a half day to summarize what's happening in a group
doug: having a narrative, it helps to have the people to get into the mindset on how it was developed
alex: I was trying to figure out
how it was the good way to have examples.
... Changing the spec for improving readability
... I treat a spec like a bible
... there are things not understandable
... and you need somewhere else to understand it
... and then you need to find the good examples.
... The companies can put good examples on the web sites.
doug: First it would be a wiki
for the documentation
... to allow large contributions
... you could have annotated version of the specification.
... with links to test and documentation.
... We could use an hyperlinking systems (winking)
murray: You think about documentation as something separated from the spec
doug: there are different kind of
materials for different targets
... some devs say: "This doesn't help me."
murray: Unix man pages. What
people need prototypes.
... but man pages were useful for everyone else.
doug: it is one way of looking at
... good documentation for developers will not be a spec on a wiki. It is an antipattern.
... spec, tests and docs are different products
yehuda: specs should be a primary target.
murray: html4 was a
... the world is moving at a fast pace.
... people are left behind in the dust.
doug: We are focusing on the documentation here
yehuda: the spec for implementers
and docs for developers it is a false line.
... I think we should have people for improving the spec into a user manual.
<cyns> +1 to yehuda
karl: I do not think it is the
best use of our time
... there are plenty of audiences for Web documentation
... documentation in specification will explode
doug: The specification has already a lot of arguments on normative stuff
<shawn> +1 to having normative info in the spec, and non-norm doc separate
doug: documentations will be hard and have a lot of discussions.
karl: I think you are yehuda very knowledgeable
<marie> [Susan informs all of you that lunch is served in Salon 6-9 - starting now]
ernesto: The spec is mainly for
... the html4 was great but it was not for implementers
... we are should not mix the two audiences
chris: developer mode would be a
fantastic idea. But we could still have granularity in
... Developers want to solve specific issues.
... this is an important part of the documentation.
cyns: the thing I find missing is
"what is the real answer"
... it's very hard for a developer to know what the author should do.
... We are missing the what
... we are also missing the web developer focused reference documentation
... W3C needs to have these answers
shawn: we do have a couple of examples
<Zakim> shawn, you wanted to say some are, eg WAI-ARIA and to say WCAG 2
shawn: WAI-ARIA, WCAG2.0 have such material -- where normative info is in the spec, and non-norm info is linked but separate.
<wycats> ARIA is really great
<marie> kudos to aria and i18 docs
don: I was not clear about the scope
<paul_irish> marie: +1
doug: The focus is people creating the content.
chris: It is a pragmatic approach.
eliot: Working with the spec
writer OR working on documentation content.
... it is not necessary a "OR" it could be a "AND".
<cyns> +1 to eliot
eliot: It could be part of an education system
<wycats> we need better documentation for the documentation writers
eliot: on the spec writer front
it would be possible to improve
... the way we write specifications.
doug: do we have action items
<scribe> ACTION: chris to work with kimberly on reaching out to WASP ILG about doing translations. [recorded in http://www.w3.org/2011/11/02-webdocs-minutes.html#action01]
<scribe> ACTION: molly to look at what has been done in HTML5 for creating developer documentation [recorded in http://www.w3.org/2011/11/02-webdocs-minutes.html#action02]
<wycats> can we add "author mode" to the action item so it doesn't get lost?
<scribe> ACTION: doug to bring up discussion in W3C staff about the "This week in the WG" [recorded in http://www.w3.org/2011/11/02-webdocs-minutes.html#action03]
make logs public
<paul_irish> email firstname.lastname@example.org
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/Aaron/Arron Eicholz/ Succeeded: s/Ernest/Ernesto/ Succeeded: s/Hiroto ccc/Hiroto Yahagi/ Succeeded: s/Shane/Sharon/ FAILED: s/Shane RTuss, Nobility/Sharron Rush Knowbility/ Succeeded: s/James xxx, WAI/Char James-Tanny, participant in WAI EOWG/ Succeeded: s/xxxx aaaa/Cynthia Shelly, Microsoft, Accessible app development, HTML & PF WGs/ Succeeded: s/zzzz bbbb/Jennifer Sutton, participant in WAI EOWG/ Succeeded: s/yahuda:/yehuda:/g Succeeded: s/hald/half/ Succeeded: s/WAI-ARIA, WCAG2.0 has kind of similar materials/WAI-ARIA, WCAG2.0 have such material -- where normative info is in the spec, and non-norm info is linked but separate./ Found ScribeNick: karl Found Scribe: karl dubost WARNING: No "Present: ... " found! Possibly Present: DavidKim Kimberly Sharron aaron alex alexmog brutzman chris cyns don doug eliot ernesto ernesto_jimenez florian hiroto joined junya karl kimberlyblessing marie mchampion_ murray paul_irish scribenick shawn shepazu tobie webdocs wycats yehuda You can indicate people for the Present list like this: <dbooth> Present: dbooth jonathan mary <dbooth> Present+ amy Got date from IRC log name: 02 Nov 2011 Guessing minutes URL: http://www.w3.org/2011/11/02-webdocs-minutes.html People with action items: chris doug molly[End of scribe.perl diagnostic output]