10:18:53 RRSAgent has joined #web-platform-doc 10:18:57 logging to https://www.w3.org/2025/03/26-web-platform-doc-irc 10:18:57 RRSAgent, do not leave 10:18:58 RRSAgent, this meeting spans midnight 10:18:58 RRSAgent, make logs public 10:18:59 Meeting: Web platform documentation 10:18:59 Chair: Florian Scholz 10:18:59 Agenda: https://github.com/w3c/breakouts-day-2025/issues/10 10:18:59 Zakim has joined #web-platform-doc 10:19:00 Zakim, clear agenda 10:19:00 agenda cleared 10:19:00 Zakim, agenda+ Pick a scribe 10:19:01 agendum 1 added 10:19:01 Zakim, agenda+ Reminders: code of conduct, health policies, recorded session policy 10:19:01 agendum 2 added 10:19:01 Zakim, agenda+ Goal of this session 10:19:02 agendum 3 added 10:19:02 Zakim, agenda+ Discussion 10:19:02 agendum 4 added 10:19:02 Zakim, agenda+ Next steps / where discussion continues 10:19:03 agendum 5 added 10:19:03 Zakim, agenda+ Adjourn / Use IRC command: Zakim, end meeting 10:19:03 agendum 6 added 10:19:04 breakout-bot has left #web-platform-doc 10:26:33 tidoust has joined #web-platform-doc 20:43:46 fscholz has joined #web-platform-doc 20:43:52 wbamberg has joined #web-platform-doc 20:53:28 fscholz has joined #web-platform-doc 20:53:43 unextro has joined #web-platform-doc 21:00:21 plh has joined #web-platform-doc 21:01:06 zakim, who is present? 21:01:06 I don't understand your question, plh. 21:01:11 zakim, who is here? 21:01:11 Present: (no one) 21:01:12 dom has joined #web-platform-doc 21:01:13 On IRC I see plh, unextro, fscholz, wbamberg, tidoust, Zakim, RRSAgent 21:01:40 present+ 21:01:45 present plh, fscholz 21:01:48 estelle has joined #web-platform-doc 21:01:49 present+ plh, fscholz 21:02:02 present+ dipika 21:02:18 present+ estelle, Daniel Beck 21:02:32 Present+ 21:02:54 present+ eric holscher 21:03:09 present+ joe walker 21:03:13 jwalker has joined #web-platform-doc 21:03:17 ddbeck has joined #web-platform-doc 21:03:22 zakim, who is here? 21:03:22 Present: wbamberg, plh, fscholz, dipika, estelle, Daniel, Beck, dom, eric, holscher, joe, walker 21:03:25 On IRC I see ddbeck, jwalker, estelle, dom, plh, unextro, fscholz, wbamberg, tidoust, Zakim, RRSAgent 21:03:47 present+ jwalker 21:04:30 present+ ddbeck 21:05:24 scribenick: wbamberg 21:06:16 fscholz: the web platform consists of many interconnected bits maintained by different groups (TPAC slide from tidoust) 21:07:05 fscholz: presented at TPAC tools for understanding what is in the web platform and how to document it 21:07:52 fscholz: web platform is massive and growing (e.g. 15000 features in BCD) 21:08:55 fscholz: we are trying to help web developers to navigate the web platform in a more accessible way than the specifications (https://diataxis.fr/) 21:09:34 fscholz: technical documentation is still the primary way developers learn how to code 21:10:41 fscholz: we're trying to understand what people don't understand (e.g. web security survey on MDN) 21:13:59 fscholz: how can the different groups coordinate better so we can have better docs that meet the needs of web developers: proposal is to make a Web Docs CG to coordinate 21:15:40 lola has joined #web-platform-doc 21:16:55 dom: quite supportive of the idea of bringing more coordination here. keyword is adoption: all of us are here because we think the tech is worth it, we want people to use it 21:17:26 dom: documentation is a key part of adoption, good if this group can bring a more systematic approach 21:18:32 dipika: likes the idea. This would need a buy-in from browser implementors and spec authors. We ened subject matter experts to review docs (e.g. spec authors) to make realistic examples 21:19:20 dipika: say what the feature is and where you need it, so devs can see the value in making use of it. Spec authors can help because they know why they have introduced it 21:19:43 dipika: tech writers are the bridge between spec authors and the world 21:21:10 fscholz: yes: we would like to invite chairs to talk about their specs. SWAG has been successful in getting input from spec authors 21:21:49 lola: would not want to make SME review a barrier to getting docs written 21:22:56 lola: TAG has explainer's explainer. This is a requirement to write a spec in as clear a language as possible, written by spec author and giving a high level overview. 21:23:53 lola: also have people going to other groups asking for information, meet spec authors where they are, rather than trying to get them to come into our space. 21:24:03 tantek has joined #web-platform-doc 21:24:56 dom: +1 to meeting the spec authors where they are, and making us of explainers 21:25:27 dom: also code samples is a field where tech writers can benefit from spec authors 21:26:23 dom: big enabler for SWAG was the analysis that led to the creation of the group 21:26:54 dom: tech writers can give value by bringing analysis of the state of documentation 21:28:09 fscholz: with compute pressure API I was able to give detailed feedback on the spec, effectively adding QA to it, becuase these were some of the first non-spec-author eyes on the spec. 21:28:36 dom: so timing is important: typically explainer comes in before the spec, so it may be a good time for feedback. 21:30:26 vadim: one barrier between developers and specs is the language barrier. Supporting communities that support docs not in English could be a part of the remit of this group 21:31:37 fscholz: yes, in the charter we have listed many different docs sites, and it makes sense to take into account what others are doing, and try to get them to take part 21:31:50 scribe+ 21:32:23 wbamberg: re SWAG, it's been a place to get a lot of access to people with lots of knowledge and lots of interest in adoption 21:32:55 .... based on a realization that adoption wasn't where it needed to be, which motivated people to get docs better based on the assessment that they weren't as good as they needed to be 21:33:13 ... this created a valuable virtuous cycle in making it worth their time 21:33:46 .... I hope we can reproduce something similar beyond SWAG 21:33:49 scribe- 21:33:57 WILL: SWAG. I felt lucky to be close to people close to the spec who care about adoption. Part was the study, but part was the realization that the guidance was too complicated or inconsistent. People came to the meeting with the goal of making docs better so we had people who wanted to work on this and it was worth their time. People are experts 21:33:57 are busy. If they put it in docs, they don’t have to continue explaining. WHen people understand that, it’s beneficial. It might be overoptimistic to replicate that. 21:34:31 ddbeck: in the charter the list of sites is long and has varied audiences 21:35:00 ddbeck: maybe actual docs production is not in the scope of this 21:36:01 ddbeck: also consider bringing web developers in scope, so they can share their experiences 21:36:28 fscholz: yes, would like to get a better perspective on the experiences of developers trying to understand wp features 21:37:03 fscholz: it is a worry to put too much into this CG. We want to be focused and for this to be a place of practice. 21:38:10 fscholz: is the scope of work in the charter too long? If we could just have 2 or 3 things, what would they be? 21:38:51 dom: having a broad charter is not problematic: they key question is, how will you bring people in and keep them engaged 21:40:03 dom: what should be our priorities? maybe start with inviting SMEs to the group? 21:40:34 dom: won't expect many long-term participants, but maybe a core and people may come and go 21:41:09 dom: the key thing is trying it out, putting effort into getting people in and iterating 21:42:21 dipika: not everyone needs to be in the group all the time: people come and get help when they need it 21:43:01 lola: there used to be a web education cg, it closed down, do we know why? Can we learn anything from that? 21:44:24 dom: web education was a somewhat different focus, but worth talking to Chris, who was involved with this 21:44:47 scribe+ 21:45:05 wbamberg: +1 to dipika - a consulting model, a docs helpdesk model 21:45:24 ... a prioritized todo list, a sense we're working on the right things would be a great outcome 21:45:39 ... I don't think we need to expect people to stay for long 21:46:04 ... e.g. a couple of years ago, we had this big focus on updating DOM documentation; we did it, and then moved on 21:46:12 ... similar to what is happening on security with SWAG 21:46:15 scribe- 21:46:22 s/DOM/performance/ 21:47:23 fscholz: with the perf docs we made a plan of what the docs should look like and worked on it with the spec authors. Now the basics are in place it is easier for everyone (including spec authors) to maintain them in the future. 21:48:17 dom: make sure we advertise the group to W3C working groups to know they have the resource available 21:48:44 dom: organizing something very visible at TPAC, like documentation helpdesk 21:49:24 dom: e.g. yesterday we had WebRTC meeting and discussed deprecating an API, and the corresponding docs updates. 21:49:36 dom: not only in MDN but in otehr doc sources on the web 21:50:31 dom: help WGs understand better about how to communicate spec changes (e.g. deprecations) to developers 21:50:57 dom: would be great if WGs knew there was a docs resource they could call on in situations like this 21:51:54 fscholz: Anssi from Intel: other horizontal aspects like security/privacy, performance 21:53:11 fscholz: encouraged by this conversation. Create a Slack channel to work on the CG submission. 21:53:44 dom: deadline for charter input? 21:54:22 fscholz: will consider, 2 weeks? 21:54:40 fscholz: will take action item to move CG proposal forward 21:59:37 Thanks everyone! How do I generate the minutes from here? 22:00:12 zakim, end the meeting 22:00:12 As of this point the attendees have been wbamberg, plh, fscholz, dipika, estelle, Daniel, Beck, dom, eric, holscher, joe, walker, jwalker, ddbeck 22:00:12 RRSAgent, please draft minutes 22:00:13 I have made the request to generate https://www.w3.org/2025/03/26-web-platform-doc-minutes.html Zakim 22:00:20 I am happy to have been of service, wbamberg; please remember to excuse RRSAgent. Goodbye 22:00:20 Zakim has left #web-platform-doc 22:03:51 rrsagent, please excuse us 22:03:51 I see no action items