18:21:25 RRSAgent has joined #webdocs 18:21:25 logging to http://www.w3.org/2011/11/02-webdocs-irc 18:21:37 RRSAgent, make logs public 18:21:38 mchampion_ has joined #webdocs 18:21:52 scribenick: karl 18:22:21 scribe: karl dubost 18:23:03 chair: Doug Scheppers 18:23:20 Meeting: Web Developer Documentation 18:23:33 kimberlyblessing has joined #webdocs 18:23:47 RRSAgent, make minutes 18:23:47 I have made the request to generate http://www.w3.org/2011/11/02-webdocs-minutes.html karl 18:24:10 RRSAgent, make logs public 18:24:26 Topic: Introduction 18:24:33 doug scheppers, w3c 18:24:42 chris David Mills, Opera Software 18:24:56 Masataka Yakura, Mitsue Links 18:26:04 Murray Malhoney 18:26:26 Yamada, Internet Academy 18:26:40 Hiroki Yamada, W3C fellow, Internet Academy 18:26:51 (working on documentation on w3c web sites) 18:27:04 Don Brutzman, 3D consortium 18:27:27 Eliott Graff, Editor lead for dev doc at Microsoft 18:27:33 Kimberley Blessing, Comcast 18:27:59 Aaron xxx, Microsoft 18:28:34 shepazu has joined #webdocs 18:28:34 Yahuda Katz, Ruby On rails 18:28:53 s/Aaron/Arron Eicholz 18:29:14 Paul Irish, Google 18:29:14 Karl Dubost, Opera Software 18:29:14 Marie-Claire Forgues, W3C, Education group 18:30:40 Ernest Jimenez, Vodafone 18:31:03 s/Ernest/Ernesto/ 18:31:08 James xxx, WAI 18:31:16 xxxx aaaa 18:31:17 brutzman has joined #webdocs 18:31:19 paul_irish has joined #webdocs 18:31:20 Shawn Henry, W3C 18:31:28 zzzz bbbb 18:31:32 tobie has joined #webdocs 18:31:44 Hiroto ccc, W3C system team 18:32:17 s/Hiroto ccc/Hiroto Yahagi/ 18:32:42 Tobie Langel, Facebook 18:32:49 Shane Russ, Nobility 18:32:56 s/Shane/Sharon/ 18:33:04 marie has joined #webdocs 18:33:29 Topic: History 18:33:53 chris: I chair the web education community group 18:34:10 ... we want to provide a vendor neutral canonical source of documentation 18:34:10 http://www.w3.org/community/webed/ 18:34:16 ... focused first on geeks 18:34:32 ... but also web designers, marketing 18:34:49 shawn has joined #webdocs 18:35:00 ... the curriculum project has the aim to create a curriculum for University 18:35:18 ... We would like to develop a certification effort for training 18:35:28 s/Shane RTuss, Nobility/Sharron Rush Knowbility/ 18:35:29 ... We want to form an outreach group 18:36:04 rrsagent, draft minutes 18:36:04 I have made the request to generate http://www.w3.org/2011/11/02-webdocs-minutes.html shawn 18:36:08 ... There are good universities, but the things which are taught are sometimes pretty bad 18:36:20 doug: We want the documentation to be CC-BY 18:36:38 ... so to have attributions, but make it possible for people to reuse it freely 18:36:48 ... Each person would not have to start from scratch. 18:37:08 hiroto has joined #webdocs 18:37:12 yahuda: about curriculum, most of the people being Web developers didn't learn at schools. 18:37:17 s/James xxx, WAI/Char James-Tanny, participant in WAI EOWG/ 18:37:39 chris: all about pragmatism 18:37:40 ... How do we get the words out to university once we have the curriculum. 18:37:49 doug: We have to stay pragmatism 18:38:22 kimberly: The information needs to be made available 18:38:26 s/xxxx aaaa/Cynthia Shelly, Microsoft, Accessible app development, HTML & PF WGs/ 18:38:34 junya has joined #webdocs 18:38:35 ... if the schools are using it or not is secondary. 18:38:40 need to tap professionnals 18:38:46 ... some schools are asking me to teach in school. 18:38:52 ... so it can be useful. 18:39:07 yahuda: You are a practitioner. 18:39:15 s/zzzz bbbb/Jennifer Sutton, participant in WAI EOWG/ 18:39:23 Kimberly: evangelists can use this materials 18:39:31 ... the students will be able to use it. 18:40:11 chris: We are trying to help local educators, more than being perfect 18:40:30 ... We also want international subgroups. 18:40:46 ... there are passionate group of French and Japanese people involved in Web education Web standards 18:40:56 equivalent quality 18:40:59 ... to have equivalent qualities and not necessary exact translation. 18:41:13 ... It is difficult to do for a local company. 18:41:22 DavidKim has joined #webdocs 18:41:24 doug: Having it done by local communities 18:41:30 ... is a lot more effective. 18:41:40 ... Hiro has made a lot of Web sites on the W3C site 18:41:44 wycats has joined #webdocs 18:41:47 ... and he is translating to Japanese 18:41:52 Yehuda, btw :) 18:42:05 ... and finally to reach out Japanese developer community 18:42:22 s/yahuda:/yehuda:/g 18:42:47 kimberly: the Web standard project has a lot of persons. We have a 100 individuals. 18:43:01 ... We have already a lot of people in different languages 18:43:13 ... This is a group of people we can reach out. 18:43:31 http://www.webstandards.org/action/ilg/ 18:43:31 doug: I have been talking to people I know already. 18:43:43 ... but there are other people. 18:44:04 yehuda: some people are reading W3C specs 18:44:18 ... The HTML5 spec did a good job at it. 18:44:31 ... JSfiddle did also a good job. 18:45:13 chris: better stylesheets, prose more readable in the specifications could be one of the goals. 18:45:45 q? 18:46:04 cyns has joined #webdocs 18:46:14 q+ 18:46:19 murray: years ago, w3c wanted to have technical writers 18:46:20 Sharron has joined #webdocs 18:46:21 q+ 18:46:21 q? 18:46:37 ... but we kind of move away from that. 18:46:46 doug: We do not have that much money. 18:47:03 shawn: It's not a lack of interests. 18:47:26 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 18:47:27 Zakim has joined #webdocs 18:47:39 q+ cyns 18:47:44 q+ karl 18:47:49 ack cyns 18:48:01 cyns: I would like to see more howto, step by step documentation 18:48:08 ... and cases studies 18:48:22 doug: a bit like web standards sherpa. 18:48:30 (link? 18:48:30 ) 18:48:35 http://webstandardssherpa.com/ 18:48:39 http://webstandardssherpa.com/ 18:48:50 cyns: working with them would be good 18:49:02 ack ka 18:49:40 karl was hired to help with readability of specs. it was very difficult to convince people to improve the readability of specs. 18:50:24 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. 18:50:36 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. 18:50:48 q+ brutzman 18:50:57 doug: I agree with both of you (yehuda, karl) 18:51:12 ... Work on getting documentation good. 18:51:42 ... The people writing html5rocks try to reverse engineer what the editor meant 18:51:59 ... There are usually huge thread about hidden editors 18:52:01 q? 18:52:16 q+ tobie 18:52:19 q+ about narratives of Web standards discussions 18:52:28 q+ to ask about narratives of Web standards discussions 18:52:35 q+ 18:52:37 q? 18:53:01 alexmog has joined #webdocs 18:53:06 yehuda: the spec are already good. It would be good to improve them for webdevs 18:53:12 q+ 18:53:14 q+ 18:53:17 cyns: It was easy in the past 18:53:23 q+ murray 18:53:24 ack brut 18:54:33 q- 18:54:35 brutzman: The documentation they want for objects is how the object is working. hopefully 3D will become a first class object. 18:54:49 doug: we will not be able to block people 18:55:02 ... so the community process will reflect what people want to do . 18:55:08 ... please write down on the wiki 18:55:40 Tobie: AppCache is done for one thing, and they use it for something. There is a big divide 18:55:48 ... in between what the spec is meant for 18:55:52 q+ yehuda 18:55:56 ... and what the people are using it for 18:56:07 doug: that's why we need to improve use cases 18:56:08 q- 18:56:23 tobie: we need also to know what is implemented where 18:56:28 ... something implemented nowhere 18:56:32 ... is useless 18:56:42 doug: test suites can help achieve that 18:56:48 q? 18:56:51 ack to 18:57:07 aaron: test suites provide two levels of information 18:57:17 ... is it implemented and the quality of implementation 18:57:30 doug: for svg the test suite becomes documentation. 18:57:33 rrsagent, log team 18:57:33 I'm logging. I don't understand 'log team', marie. Try /msg RRSAgent help 18:57:33 ack karl 18:57:33 karl, you wanted to ask about narratives of Web standards discussions 18:58:20 karl: difficult sometimes to understand what is in mailing lists. Would be good to have someone telling the "story" 18:58:31 ... kind of a summary 18:59:09 ... i'm now following webapps and html5 and it takes me a hald day to summarize what's happening in a group 18:59:17 s/hald/half 18:59:28 q? 18:59:36 doug: having a narrative, it helps to have the people to get into the mindset on how it was developed 18:59:37 ack alex 18:59:53 alex: I was trying to figure out how it was the good way to have examples. 19:00:17 ... Changing the spec for improving readability 19:00:33 ... I treat a spec like a bible 19:00:41 ... there are things not understandable 19:00:49 ... and you need somewhere else to understand it 19:01:03 ... and then you need to find the good examples. 19:01:29 ... The companies can put good examples on the web sites. 19:01:59 doug: First it would be a wiki for the documentation 19:02:04 ... to allow large contributions 19:02:14 ... you could have annotated version of the specification. 19:02:25 ... with links to test and documentation. 19:02:43 ... We could use an hyperlinking systems (winking) 19:02:45 q? 19:02:58 ack murr 19:03:13 murray: You think about documentation as something separated from the spec 19:03:28 doug: there are different kind of materials for different targets 19:03:43 ... some devs say: "This doesn't help me." 19:04:10 murray: Unix man pages. What people need prototypes. 19:04:13 q? 19:04:21 ... but man pages were useful for everyone else. 19:04:34 doug: it is one way of looking at things 19:05:00 ... good documentation for developers will not be a spec on a wiki. It is an antipattern. 19:05:21 ... spec, tests and docs are different products 19:05:22 ack ye 19:05:28 q? 19:05:52 yehuda: specs should be a primary target. 19:06:15 murray: html4 was a documentation. 19:06:42 ... the world is moving at a fast pace. 19:06:54 ... people are left behind in the dust. 19:07:13 doug: We are focusing on the documentation here 19:07:26 q+ karl 19:07:40 q+ 19:07:43 q+ 19:07:43 yehuda: the spec for implementers and docs for developers it is a false line. 19:07:45 q+ karl 19:08:12 q- 19:08:15 ... I think we should have people for improving the spec into a user manual. 19:08:24 +1 to yehuda 19:08:51 q+ tobie 19:09:15 q+ chris 19:09:36 q+ 19:10:18 q? 19:10:27 karl: I do not think it is the best use of our time 19:10:37 ... there are plenty of audiences for Web documentation 19:10:46 ... documentation in specification will explode 19:10:57 florian has joined #webdocs 19:11:19 q+ 19:11:21 doug: The specification has already a lot of arguments on normative stuff 19:11:33 q? 19:11:41 +1 to having normative info in the spec, and non-norm doc separate 19:11:52 ... documentations will be hard and have a lot of discussions. 19:11:59 q+ to say some are, eg WAI-ARIA 19:13:04 karl: I think you are yehuda very knowledgeable 19:13:06 q+ to say WCAG 2 19:13:07 q- 19:13:27 [Susan informs all of you that lunch is served in Salon 6-9 - starting now] 19:13:41 ernesto: The spec is mainly for developers 19:13:52 ... the html4 was great but it was not for implementers 19:14:20 ... we are should not mix the two audiences 19:14:37 ack karl 19:14:42 q+ 19:14:45 ack me 19:14:49 ack e 19:14:50 ack tobie 19:14:59 chris: developer mode would be a fantastic idea. But we could still have granularity in documentation. 19:15:03 ack chris 19:15:19 ... Developers want to solve specific issues. 19:15:39 ... this is an important part of the documentation. 19:15:48 ack cyns 19:16:12 cyns: the thing I find missing is "what is the real answer" 19:16:29 ... it's very hard for a developer to know what the author should do. 19:16:44 ... We are missing the what 19:17:03 ... we are also missing the web developer focused reference documentation 19:17:12 ... W3C needs to have these answers 19:17:30 e.g., "Understanding 1.3.1" links in http://www.w3.org/TR/WCAG20/ also fyi: http://www.w3.org/WAI/WCAG20/quickref/ 19:17:31 shawn: we do have a couple of examples 19:17:45 ack shawn 19:17:45 shawn, you wanted to say some are, eg WAI-ARIA and to say WCAG 2 19:17:55 ... WAI-ARIA, WCAG2.0 has kind of similar materials 19:17:56 q+ 19:18:07 q? 19:18:13 ARIA is really great 19:18:13 close queue 19:18:15 ack brutzman 19:18:28 kudos to aria and i18 docs 19:18:32 don: I was not clear about the scope 19:18:34 marie: +1 19:18:44 doug: The focus is people creating the content. 19:19:10 chris: It is a pragmatic approach. 19:19:11 ack eliot 19:19:40 eliot: Working with the spec writer OR working on documentation content. 19:20:03 ... it is not necessary a "OR" it could be a "AND". 19:20:06 +1 to eliot 19:20:12 ... It could be part of an education system 19:20:22 we need better documentation for the documentation writers 19:20:32 ... on the spec writer front it would be possible to improve 19:20:39 ... the way we write specifications. 19:20:42 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./ 19:20:47 q? 19:21:18 doug: do we have action items 19:21:59 ACTION: chris to work with kimberly on reaching out to WASP ILG about doing translations. 19:23:10 http://www.w3.org/community/webed/ 19:23:17 public-evangelist@w3.org 19:24:15 http://lists.w3.org/Archives/Public/public-evangelist/ 19:25:12 ACTION: molly to look at what has been done in HTML5 for creating developer documentation 19:25:33 can we add "author mode" to the action item so it doesn't get lost? 19:25:50 ACTION: doug to bring up discussion in W3C staff about the "This week in the WG" 19:26:11 make logs public 19:26:20 rrsagent, make logs public 19:26:32 email schepers@w3.org 19:26:32 rrsagent, make minutes 19:26:32 I have made the request to generate http://www.w3.org/2011/11/02-webdocs-minutes.html karl 19:28:12 hiroto has joined #webdocs 19:52:25 myakura has joined #webdocs 20:20:26 myakura has joined #webdocs 20:28:56 ernesto_jimenez_ has joined #webdocs 20:29:45 arronei has joined #webdocs 20:32:37 karl has joined #webdocs 20:34:41 shawn has joined #webdocs 20:35:29 shawn has left #webdocs 20:36:33 hiroki has joined #webdocs 20:38:08 tobie has joined #webdocs 20:40:29 shepazu has joined #webdocs 20:45:36 myakura has joined #webdocs 21:14:55 shepazu has joined #webdocs 21:31:19 hiroki has joined #webdocs 21:33:20 tobie has joined #webdocs 21:37:56 Zakim has left #webdocs 21:38:41 arronei has joined #webdocs 21:40:33 eliot_ has joined #webdocs 21:41:36 karl has joined #webdocs 21:42:54 ernesto_jimenez has joined #webdocs 21:42:56 eliot_ has left #webdocs 21:44:22 ernesto_jimenez has joined #webdocs 22:15:37 tobie has joined #webdocs 22:18:49 RRSAgent, bye 22:18:49 I see 3 open action items saved in http://www.w3.org/2011/11/02-webdocs-actions.rdf : 22:18:49 ACTION: chris to work with kimberly on reaching out to WASP ILG about doing translations. [1] 22:18:49 recorded in http://www.w3.org/2011/11/02-webdocs-irc#T19-21-59 22:18:49 ACTION: molly to look at what has been done in HTML5 for creating developer documentation [2] 22:18:49 recorded in http://www.w3.org/2011/11/02-webdocs-irc#T19-25-12 22:18:49 ACTION: doug to bring up discussion in W3C staff about the "This week in the WG" [3] 22:18:49 recorded in http://www.w3.org/2011/11/02-webdocs-irc#T19-25-50