Web Developer Documentation -- 02 Nov 2011

<scribe> scribenick: karl

<scribe> scribe: karl dubost

Introduction

doug scheppers, w3c

chris David Mills, Opera Software

Masataka Yakura, Mitsue Links

Murray Malhoney

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

History

chris: I chair the web education community group
... we want to provide a vendor neutral canonical source of documentation

<marie> http://www.w3.org/community/webed/

chris: focused first on geeks
... 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 outreach group
... 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 this materials
... 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 communities
... 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.

<kimberly> http://www.webstandards.org/action/ilg/

doug: I have been talking to people I know already.
... but there are other people.

yehuda: some people are reading W3C specs
... 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.

(link?

)

<kimberly> http://webstandardssherpa.com/

<wycats> http://webstandardssherpa.com/

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 (yehuda, karl)
... 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 block people
... 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 divide
... 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 things
... 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 documentation.
... 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 developers
... 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 documentation.
... 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> e.g., "Understanding 1.3.1" links in http://www.w3.org/TR/WCAG20/ also fyi: http://www.w3.org/WAI/WCAG20/quickref/

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

close queue

<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]

<shepazu> http://www.w3.org/community/webed/

public-evangelist@w3.org

<paul_irish> http://lists.w3.org/Archives/Public/public-evangelist/

<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 schepers@w3.org

- DRAFT -

Web Developer Documentation

02 Nov 2011

Attendees

Contents

Introduction

History

Summary of Action Items

Scribe.perl diagnostic output