├── w3c.json ├── CODE_OF_CONDUCT.md ├── LICENSE.md ├── CONTRIBUTING.md ├── README.md ├── meetings ├── 2025-10-21.md ├── 2025-07-15.md ├── 2025-08-12.md ├── 2025-08-26.md ├── 2025-06-17.md ├── 2025-05-20.md ├── 2025-05-06.md ├── 2025-10-07.md ├── 2025-09-09.md ├── 2025-07-29.md ├── 2025-04-22.md ├── 2025-12-02.md ├── 2025-11-10-tpac.md ├── 2025-11-11-tpac.md ├── 2025-11-13-tpac.md └── 2025-06-03.md └── charter.md /w3c.json: -------------------------------------------------------------------------------- 1 | { 2 | "group": [166442] 3 | , "contacts": ["ij@w3.org"] 4 | , "repo-type": "cg-report" 5 | } 6 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | All documentation, code and communication under this repository are covered by the [W3C Code of Conduct](https://www.w3.org/policies/code-of-conduct/). 4 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | All Reports in this Repository are licensed by Contributors 2 | under the 3 | [W3C Software and Document License](https://www.w3.org/copyright/software-license/). 4 | 5 | Contributions to Specifications are made under the 6 | [W3C CLA](https://www.w3.org/community/about/process/cla/). 7 | 8 | Contributions to Test Suites are made under the 9 | [W3C 3-clause BSD License](https://www.w3.org/copyright/3-clause-bsd-license-2008/) 10 | 11 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Documentation Community Group 2 | 3 | This repository is being used for work in the W3C Documentation Community Group, governed by the [W3C Community License 4 | Agreement (CLA)](http://www.w3.org/community/about/process/cla/). To make substantive contributions, 5 | you must join the CG. 6 | 7 | If you are not the sole contributor to a contribution (pull request), please identify all 8 | contributors in the pull request comment. 9 | 10 | To add a contributor (other than yourself, that's automatic), mark them one per line as follows: 11 | 12 | ``` 13 | +@github_username 14 | ``` 15 | 16 | If you added a contributor by mistake, you can remove them in a comment with: 17 | 18 | ``` 19 | -@github_username 20 | ``` 21 | 22 | If you are making a pull request on behalf of someone else but you had no part in designing the 23 | feature, you can remove yourself with the above syntax. 24 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG 2 | 3 | This is the repository for the [W3C Docs Community Group](https://www.w3.org/community/docs-cg/). This group is an open community with the mission to ensure web developers and designers worldwide have the best information available so they can build things on the web platform. For more details, read our [charter](charter.md). 4 | 5 | This group is open to anyone to join. If you would like to join, please visit [this](https://www.w3.org/community/docs-cg/join) page. You will be asked to create a W3C account if you do not have one already. If you are affiliated with a W3C Member organization then you will have to ask your Advisory Committee representative to add you to the group. 6 | 7 | We are in the `#docs-cg` channel on the [W3C Community Slack](https://w3ccommunity.slack.com/archives/C08KNG3GFEF) to organize and do work asynchronously between meetings. To get an invite to the W3C Community Slack, please visit [this](https://www.w3.org/slack-w3ccommunity-invite) page. 8 | 9 | Our minutes are posted in this repo after every call. 10 | 11 | You can find Docs CG meetings on the [Documentation Community Group Calendar](https://www.w3.org/groups/cg/docs-cg/calendar/). 12 | -------------------------------------------------------------------------------- /meetings/2025-10-21.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG call, 2025-10-21 2 | 3 | Present: Lola, Florian, Eric, Estelle, Vadim (late) 4 | 5 | Scribes: Florian, Estelle 6 | 7 | ## Agenda 8 | 9 | 1. TPAC Agenda 10 | - [General Meeting](https://github.com/w3c-cg/webdocs/issues/25) 11 | - [Explainers](https://github.com/w3c-cg/webdocs/issues/24) 12 | - [Conversational Docs](https://github.com/w3c-cg/webdocs/issues/26) 13 | 2. [Update charter to include i8n](https://github.com/w3c-cg/webdocs/issues/23) 14 | 15 | ## Notes 16 | 17 | ### TPAC 18 | 19 | - Florian created issues and added tentative agendas for our three Docs CG sessions 20 | - Florian confirmed with Dom about the "Conversational AI" session, co-hosting with Florian 21 | - Lola will host the Explainer session 22 | - Florian will host the General Docs CG session 23 | - Lola: Which sessions do we want to join? 24 | - Florian: https://github.com/w3c/tpac2025-breakouts/issues/52 25 | Try to attend: 26 | - web components 27 | - i8n 28 | - web app sec 29 | - web identity & credentials adoption cg (https://passkeys.dev) 30 | - ACD 31 | - Web Views 32 | - WebDX 33 | - General session 34 | - (Florian presents agenda) 35 | - (We agree on confirmed agenda) 36 | - Explainer session 37 | - (Florian presents agenda) 38 | - Lola to confirm agenda with TAG 39 | - Conversational Docs session 40 | - Florian to talk to Dominique about what the focus of this session should be. 41 | - Some thoughts: 42 | - It negatively impacts traffic to doc sites 43 | - AI is more personalized to the dev than our generic writing to be inclusive of everyone 44 | - MCP protocols exist that can help systems be more effective 45 | - Not sure if in scope for this session, but AI tools are 'stealing' content, which impacts funding structures among other things 46 | 47 | ## Including i18n 48 | 49 | - Lets invite the issue reporter to the TPAC session 50 | - Let meet with i18n folks in a future Docs CG call 51 | -------------------------------------------------------------------------------- /meetings/2025-07-15.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG call, 2025-07-15 2 | 3 | Present: Florian Scholz, Eric Meyer, Lola Odelola, Dipika Bhattacharya, Estelle Weyl, Alexandra Klepper, François Daoust 4 | 5 | Chair: Florian 6 | 7 | Note taker: Florian 8 | 9 | ## Agenda 10 | 11 | 1. Welcoming more new folks 12 | 2. Explainers, https://github.com/w3ctag/explainer-explainer/issues/19 13 | 3. Backlog for reference pages, https://openwebdocs.github.io/web-docs-backlog/ 14 | 4. ACD https://github.com/w3c/aria/issues/2538 15 | 5. TPAC 16 | 17 | ## Notes 18 | 19 | - Introductions 20 | 21 | ### Explainers 22 | 23 | - Explainers are usually for TAG, overview of the spec 24 | - Discssuion about usefulness of explainers 25 | - They aren't maintained though 26 | - Explainers will move into the spec 27 | - Should the Docs CG own explainers? 28 | - Explainer for explainers? Yes-> https://www.w3.org/TR/explainer-explainer/ 29 | - Guidelines for explainers in specs vs explainers as its own doc 30 | - Estelle: Should we own an index of explainers? 31 | - Estelle: Have Jeffrey join our call to discuss? 32 | - Dipika: We need explainers. We need them updated, so if that's guaranteed by moving them in the specs, that's great! 33 | - Dipika: two different groups might be inefficient for owning explainers 34 | - Lola: More like the Docs CG owning the process for explainers? 35 | - Lola: Have an auto-populated aggregation of explainers? 36 | - Lola: Let's have a workshop about this at TPAC 37 | - Francois: There are multiple mechanism that track spec proposals in known GitHub orgs, but not in personal spaces 38 | - Estelle: We probably only want to track explainers that come with specs 39 | - Francois: Philip H. also wanted to track explainers before there is a spec 40 | - Estelle: Lets discuss at TPAC 41 | 42 | ### Backlog for reference pages 43 | 44 | - Florian: Check it out, I can add new features 45 | - François: Could perhaps filter out features with negative standard positions in list of features with limited availability to help prioritize things. Patrick maintains a mapping between feature IDs and standard positions. 46 | - Florian: Can have a look. It may not impact that many features in the list. 47 | 48 | ### ACD 49 | 50 | - Lola: describes the project 51 | 52 | ### TPAC 53 | 54 | - Please see https://github.com/w3c/tpac2025-meetings/issues/59 for the proposed sessions. 55 | -------------------------------------------------------------------------------- /meetings/2025-08-12.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG call, 2025-08-12 2 | 3 | Present: Florian, Lola, Will, Dipika 4 | 5 | Chair: Florian 6 | 7 | Note takers: Florian 8 | 9 | ## Agenda 10 | 11 | 1. Explainers 12 | 13 | - What parts of the explainer doc do we want to be responsible for reviewing? https://github.com/w3c-cg/webdocs/issues/17 14 | - What do we want to see from spec authors? https://github.com/w3c-cg/webdocs/issues/18 15 | - Are there changes we want to make to the explainer-explainer? https://github.com/w3c-cg/webdocs/issues/19 16 | - Indexes of explainers 17 | - https://github.com/MicrosoftEdge/MSEdgeExplainers 18 | - https://github.com/Igalia/explainers/ 19 | 20 | 2. TPAC 21 | 22 | - Three sessions scheduled: https://github.com/w3c/tpac2025-meetings/issues/59 23 | 24 | ## Notes 25 | 26 | - Dipika: Do we want to do a pilot review for an explainer? 27 | - Lola: We can pick an explainer and try it out 28 | - Lola: *summarizes discussions from last week* 29 | - Lola: Co-owning the explainer-explainer doc 30 | - Lola: Does the explainer properly explain the design? 31 | - Dipika: What are they current review cycles? 32 | - Dipika: What value do we bring to the table? 33 | - Lola: The explainer gets send to several groups for review, e.g. a11y, privacy, TAG, etc. 34 | - Lola: So for example, Digital Credentials API: has an outdated explainer only. 35 | - Lola: The spec introduction is not enough. 36 | - Florian: Will say the Digital Credential people listen to us if we say: "go update your explainer" 37 | - Lola: TAG can block on horizontal reviews from the Docs CG 38 | - Will: Docs CG can help to make things understandable 39 | - Florian: People want to less process 40 | - Lola: We are shifting the responsibilities from TAG to Docs CG for explainer, so not more process, rather saving everyone's time 41 | - Lola: TAG just wants to technical design review 42 | - Dipika: Show up as partners and be helpful to get a good explainer out 43 | - Dipika: explainers get out of date quickly 44 | - Lola: Explainer can live in the spec / in the introduction 45 | - Lola: The problem is that the explainer in the introduction is not sufficient enough, they don't fill out the explainer template as they assume the spec itself explains things 46 | - Florian: Lifecycle of explainers, see MS and Igalia indexes. Can explainers always be given a status? 47 | - Will: What is the lifecycle here and what are the audiences? 48 | - Lola: The explainers are usually written before the spec. the audiences can be different. Google may write internal explainers and then go public with them, other times it is publicly developed within W3C WGs. 49 | - Lola: For spec updates, usually an explainer about the update gets written 50 | - Dipika: Does all information from the explainer move to the spec? Code examples? Problem statements? 51 | - Lola: Explainers are often high-level 52 | - Lola: https://github.com/mfreed7/declarative-shadow-dom/blob/master/README.md is a very detailed explainer with code examples, and lots of information. 53 | - Florian: Great explainer, speaking as Tech Writer this is great, but it is so hard to figure out if it is really what landed in the spec 54 | - Will: There are aspects here that are probably quite stable, like the problem space is relatively stable, but the solution space might have seen some updates when it was integrated with the spec. 55 | - Florian: Lets have a pilot review next Docs CG call. When is a good time for us to review explainers? How do we find good candidates 56 | - Dipika: We should not be speaking to a void, so identifying which ones is important? 57 | - Lola: People would send explainers to the Docs CG for review 58 | - Lola: For piloting we can just look at one of the latest issues: https://github.com/w3ctag/design-reviews/issues 59 | - Lola: Let's pick a few explainers now 60 | - Florian: Picking the latest 3: 61 | - Incubation: An Origin Object https://github.com/w3ctag/design-reviews/issues/1130 62 | - Incubation: patching (interleaved out-of-order streaming) https://github.com/w3ctag/design-reviews/issues/1134 63 | - Approximate Geolocation https://github.com/w3ctag/design-reviews/issues/1131 64 | - Florian: Reminder about our three TPAC sessions 65 | -------------------------------------------------------------------------------- /charter.md: -------------------------------------------------------------------------------- 1 | # W3C Documentation CG Charter 2 | 3 | ## Mission 4 | 5 | The mission of the W3C Documentation Community Group (W3C Docs CG) is to ensure web developers and designers worldwide have the best information available so they can build things on the web platform. 6 | 7 | ## Scope of work 8 | 9 | This community group will: 10 | 11 | - Plan and write new documentation for web platform technologies. 12 | - Make sure reference documentation (“the book of web platform features”) is complete. 13 | - Identify needs for guides, how-tos, and tutorials, and create them. 14 | - Work with specification authors to define best practices for web developer documentation, code examples, and information architecture. 15 | - Maintain and keep documentation up-to-date using modern approaches like docs-as-code 16 | - Develop tools to create feedback loops between standards and web developer documentation. 17 | - Coordinate documentation efforts: Collaborate with other W3C community groups, such as [WebDX](https://www.w3.org/community/webdx/), [Security](https://www.w3.org/mission/security/), [Privacy](https://www.w3.org/mission/privacy/), [Accessibility](https://www.w3.org/mission/accessibility/), [Internationalization](https://www.w3.org/mission/internationalization/), [Sustainability](https://www.w3.org/community/sustyweb/) and integrate their findings and best practices into documentation. 18 | - Be a resource for resources: map documentation sources for web developers. 19 | - Identify reliable sources of information. 20 | - Invite them to be part of the conversations in this community group. 21 | - Drive adoption (or deprecation) of web platform technologies: 22 | - Identify web platform features where sparse docs prevent adoption and understanding. 23 | - Interpret developer surveys (such as the [MDN short survey on web developer’s experience with Web Security](https://github.com/web-platform-dx/developer-research/blob/main/mdn-short-surveys/2023-05-15-security-dx/interpretation.md) and understand the role of documentation in identified shortcomings. 24 | - Ensure documentation relevance: coordinate horizontal efforts to get outdated docs updated such as by helping reach out to the right docs owners. 25 | - Be a hub for web documentation: when docs-related efforts, changes, and/or projects appear, coordinate with the relevant stakeholders to get these amplified. 26 | 27 | ## Key deliverables 28 | 29 | - Write and maintain docs in [mdn/content](https://github.com/mdn/content). See the [backlog](https://openwebdocs.github.io/web-docs-backlog/) for missing reference pages. 30 | - Identify best practices for web developer documentation. 31 | - Drive adoption and understanding of web technologies. 32 | 33 | ## Out of scope 34 | 35 | The group may produce Community Group Reports within the scope of this charter but not Specifications. 36 | 37 | ## Dependencies or liaisons 38 | 39 | - Groups 40 | - [Open Web Docs](https://openwebdocs.org) 41 | - [Web Developer Experience (WebDX) Community Group](https://www.w3.org/community/webdx/) 42 | - [Webref & spec tooling maintainers](https://www.w3.org/community/speced-cg/) 43 | - [SWAG Community Group](https://www.w3.org/community/swag/) 44 | - [TAG](https://www.w3.org/2001/tag/) (especially related to “explainers”) 45 | - [OWASP](https://owasp.org) 46 | - [OSTIF](https://ostif.org/) 47 | - [Write The Docs](https://www.writethedocs.org) 48 | - [ARIA Practices Guide Taskforce](https://www.w3.org/WAI/about/groups/task-forces/practices/) (a subgroup of ARIA WG) who owns/maintains [APG](https://www.w3.org/WAI/ARIA/apg/). 49 | - Docs sites 50 | - [MDN Web Docs](https://developer.mozilla.org) 51 | - [CanIUse](https://caniuse.com) 52 | - [web.dev](https://web.dev) 53 | - [learn.microsoft.com](https://learn.microsoft.com) 54 | - [devdocs.io](https://devdocs.io) 55 | - [Freecodecamp](https://www.freecodecamp.org) 56 | - Popular front-end sites/blogs which also document the web, for example: [css-tricks.com](https://css-tricks.com/almanac/pseudo-selectors/), [w3schools](https://www.w3schools.com), ... 57 | - Translated docs, for example: [Doka: web docs for Russian speaking developers](https://doka.guide/) 58 | 59 | ## Audience 60 | 61 | Who is this CG for? 62 | 63 | - Technical writers and other documentation practitioners to collaborate. 64 | - Web platform docs sites to share best practices. 65 | - Specification authors and implementers to give and receive feedback on documentation and specs. 66 | - Web developers to identify and request support to better the understanding of web platform technologies. 67 | -------------------------------------------------------------------------------- /meetings/2025-08-26.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG call, 2025-08-26 2 | 3 | Present: Lola, Estelle, Dipika, Patrick, Florian, Eric 4 | 5 | Chair: Lola 6 | 7 | Note takers: Florian 8 | 9 | ## Agenda 10 | 11 | 1. Intros (if necessary) 12 | 2. Explainer Horizontal Review Test 13 | - [Incubation: An Origin Object](https://github.com/mikewest/origin-api/) 14 | - [Incubation: patching (interleaved out-of-order streaming)](https://github.com/WICG/declarative-partial-updates/blob/main/patching-explainer.md) 15 | - [Approximate Geolocation](https://github.com/explainers-by-googlers/approximate-geolocation/blob/main/README.md) 16 | 17 | ## Notes 18 | 19 | - Lola: Last time we decided to do a pilot horizontal review for explainers 20 | - Lola: First one: Origin object 21 | - Lola: Docs-CG perspective is difficult. Trying not to take the TAG perspective 22 | - Lola: No clear use cases, no user research, we don't know if users want this 23 | - Lola: Incubation explainer: so very speculative at this point 24 | - Lola: Alternatives considered section is missing, but this might be fine given the state of the explainer 25 | - Patrick: I have no idea what the problem we're trying to solve here is, that makes it hard to write docs. It would be nice to see what developers have to do today, and what problems they're facing. 26 | - Florian: +1. Use cases section is missing. Not sure how to describe what devs would use this for. Not sure what the benefit is to anyone. Makes it hard to write docs. 27 | - Florian: for OriginPattern, it seems to be the same as URLPattern, which we documented last week on MDN. I don't get what OriginPattern does and how it's different. 28 | - Lola: Maybe Docs-CG could forward this feedback to TAG. Ask the question back to the author: what will this be used for? 29 | - Estelle: What the timing here? Do we need to be prior to TAG? Should we? 30 | - Lola: I think horizontal reviews get submitted all at the same time, sometimes they aren't done yet. Maybe we could be reviewing first. 31 | - Lola: We could also have channel where we collect private feedback 32 | - Lola: How easy was it to review this one? 33 | - Florian: Easy. Well written, just not clear what to use it for. 34 | - Lola: Next up is Patching (Partial, interleaved HTML streaming) 35 | - Estelle: This one was too technical for me 36 | - Lola: Alternatives considered, use case are missing here, too? 37 | - Lola: Should we even consider incubation explainers? 38 | - Lola: The question is more like "should this even be on the web platform"? So maybe it is too early? 39 | - Patrick: I think we should review as much as we can, but maybe prioritize accordingly 40 | - Florian: So here we have a very different situation that in the first explainer. It is not a simple interface addition. It comes with new conceptual information, how does this compare to existing patching mechanisms like in HTTP or other programming languages 41 | - Lola: Even if we don't understand the technical aspects, we should try to ask questions to better understand this. 42 | - Lola: Last one: Approximate Geolocation 43 | - Estelle: Feedback: Want more internationalization here. Just talks about 4 US states. Need more info from other countries with privacy and security laws. 44 | - Eric: This one is very privacy focused. Does this increase privacy or decrease it? How does it make things better for the user? 45 | - Florian: Would be cool to talk more about the different to the current Geolocation API. What will change for whom and how would you pick the old vs the new API? 46 | - Lola: "Can I document this explainer?" 47 | - Dipika: Looking at the explainer explainer. It mentions use cases and problems it solves but these are missing from this explainer. Is this an existing problem? Or is it a new problem that has come up? 48 | - Dipika: 3.3 says describe your proposal clearly with code examples, screenshots, etc. 49 | - Lola: We want to review in terms legibility of prose and code examples. Many miss the use cases or alternatives considered, privacy and security considerations. 50 | - Lola: How do feel about the timing of this? 51 | - Lola: TAG reviewed 1 explainer this week, 2 last week, and then 5 the week before that. 52 | - Estelle: In depth review would take longer 53 | - Lola: on average 3 explainers per week 54 | - Dipika: I don't have the bandwidth 55 | - Eric/Florian/Estelle: Could probably take some time for it 56 | - Lola: Todo: have a checklist for a Docs-CG review. 57 | - Lola: We could also set up a more private backchannel for reviews and then bring our thoughts to the public. 58 | - Lola: Have Francois advice us how to do a horizontal review in general 59 | - Estelle: Any update on ACD? 60 | - Lola: APA workshop was really great! 61 | - Lola: Currently thinking about the browser testing side 62 | - Lola: Delineating browser vs AT software bugs 63 | 64 | ## Actions 65 | 66 | - None but we should probably review more explainers to get experience with it and to be able to create a horizontal review checklist. Probably centered around the question "Can I document this explainer?" 67 | -------------------------------------------------------------------------------- /meetings/2025-06-17.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG call, 2025-06-17 2 | 3 | Present: Lola Odelola, Eric Meyer, Florian Scholz, Edward Loveall, Schalk Neethling, Estelle Weyl, François Daoust, Dipika Bhattacharya, Will Bamberg 4 | 5 | Chair: Lola 6 | 7 | Note taker: Will 8 | 9 | ## Agenda 10 | 11 | 1. Welcoming more new folks 12 | 2. [TPAC](https://github.com/w3c-cg/webdocs/issues/12) 13 | 3. [Documentation about using AI agents to generate code](https://github.com/w3c-cg/webdocs/issues/11) 14 | 4. [Using IRC to generate Minutes](https://github.com/w3c-cg/webdocs/issues/13) 15 | 16 | ## Notes 17 | 18 | Introductions. 19 | 20 | ## TPAC 21 | 22 | - Lola: Friday is the deadline for proposals. Regarding https://github.com/w3c-cg/webdocs/issues/12 - should we have drop-in sessions for WGs, or an MDN contribution workshop? 23 | - Estelle: both! 24 | - Explainers: help people understand how to write good explainers 25 | - Estelle: should have: (1) CG session for this group, face to face and (2) external session. Figure out how to get tech writers and spec authors to get together (technical networking). For explainers, if this is the right group then yes, but it should go somewhere 26 | - Lola: TAG owns explainer process. 27 | - Estelle: can Lola ask TAG if they are going to have an explainer session? Otherwise we will. 28 | - Lola: probably they won't because we know that explainers aren't going anywhere. 29 | - Lola might not be at TPAC, if she is, TAG and WebDX will take up much of her time. 30 | - Will: workshop with Web Components people (and anyone else who wants to work with us on their docs) 31 | - Florian: good to have some concrete topics, e.g. meeting with specific WGs like Web Components. Also work on some strategic stuff for this CG. Talk about "docs as conversations" (LLMs) at TPAC and what this means for docs. 32 | - François: haven't heard back from Web Components about whether they want to meet, usually they want to meet in breakouts. Trying to encourage them to meet in part of the main schedule. Instead of booking slots, and other approach would be to get on WG agenda and go to their meeting. Might get more WG people then. Risk of hosting our own sessions is that only docs CG people would attend. 33 | - Lola: overall: we want to meet at TPAC, we want a session that's just us, and also to meet with other grouos such as Web Components. At the moment seems like just one session for us, session is 1.5 hours. 34 | - Florian: 2 sessions: 35 | - One for kicking docs-cg off and discuss how it's been going. 36 | - One on LLMs. Invite experts to that: Dominique and also perhaps people from copilot. 37 | So at least 2 sessions, but don't schedule too much so we are free to attend other groups' sessions. 38 | 39 | ## AI agents 40 | 41 | - Lola: At 5 June WebDX meeting: AI agents are being used and it benefits the web for people using them to have correct (up to date) data. Also, we should have docs on using AI agents, and the risks of using them to generate code. 42 | - Florian: if you have docs talking about things you **shouldn't** do, agents don't understand this so well. Lola: this is guidance for humans. 43 | - Florian: also there are new attack vectors, prompt injections. 44 | - Schalk: accessibility is a big challenge for huge codebases that people don't understand. Could have Cursor rule that people can use and share. MDN web docs MCP server, your tool can use to get new info. Schalk is experimenting with making a repo of code examples with semantic/accessible HTML, and see if you can train a model on good examples. But it's a big project to make it scale. AI loves aria, struggles with complex things. but ultimately have to improve the underlying model. 45 | - Florian: for both humns and LLMs, need to agree on best practices. Best practices are not always well documented (e.g. security docs) so LLMs can't find it. So there's work in figuring out what best prsctices are (in accesibility and security, say) 46 | - Florian: found https://context7.com/mdn/content, an MCP that scrapes MDN for code blocks. Dont' know if it is good or not. Should we get something more offical going? 47 | - Lola: at least docs for humans on AI-generated code would be helpful. esp as a lot of AI code is inaccessible. 48 | 49 | ## IRC 50 | 51 | - Lola: W3C uses IRC for minutes in meetings. Do people want to use it? 52 | - Florian: still requires a scribe. I like the creepy bot that Estelle had. 53 | - Edward: having a raw log is helpful to get information behind the summarised notes. 54 | - Lola: is there a bot that scribes? 55 | - Estelle: Yes, fireflies.ai, the creepy bot. Good transcription, good summary. but creepy, will auto-attend your meetings. Edward: also https://github.com/vivek-nexus/transcriptonic (but have not tested this) 56 | - Schalk: most of these tools have the capability to specify an MCP, to make the bot post the summary to an issue. 57 | 58 | ## Ladybird and BCD 59 | 60 | - Schalk: status of ladybird and BCD? 61 | - Florian, does ladybird have versions? 62 | - Schalk: yes. would help to get stuff in sooner rather than later, so it's not such a mammoth task when we do want to support it. 63 | - Florian: bcd has criteria for when to add a browser. https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines/browsers.md#addition-of-browsers 64 | - Schalk: OK, maybe wait for alpha release. 65 | 66 | 67 | -------------------------------------------------------------------------------- /meetings/2025-05-20.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG call, 2025-05-20 2 | 3 | Present: Florian, Schalk, Geoff, Patrick, Dipika, Chris, Will, François, Estelle, Daniel 4 | 5 | Chair: Florian 6 | 7 | Note taker: Florian 8 | 9 | Joining info: 10 | 11 | To join the video meeting, click this link: https://meet.google.com/jdp-xvka-hyk 12 | Otherwise, to join by phone, dial +49 40 8081617306 and enter this PIN: 544 514 889# 13 | To view more phone numbers, click this link: https://tel.meet/jdp-xvka-hyk?hs=5 14 | 15 | ## Agenda 16 | 17 | 1. Welcoming more new folks 18 | 2. Web Component docs follow-up 19 | - Issue: https://github.com/w3c-cg/webdocs/issues/1 20 | - Meeting notes https://github.com/w3c-cg/webdocs/blob/main/meetings/2025-05-06.md 21 | - Any more thoughts since we met two weeks ago? 22 | 3. Web Security Docs 23 | - Will to present current status and outline for future work 24 | 4. Documentation feedback sources 25 | - What are sources of feedback for web platform docs? 26 | - Doc bugs filed 27 | - MDN satisfaction data 28 | - State of XYZ surveys (this was very useful for the Web Components docs discussion!) 29 | - User interviews 30 | - Would attendees of this CG be willing to be interviewed 31 | 5. Preparing topics for the next few Docs CG calls 32 | - (Florian) I'm interested in meeting up with Immersive Web CG to discuss [WebXR docs](https://github.com/openwebdocs/project/issues/158) 33 | - (Florian) Also interested in meeting up with Performance WG to discuss [Performance API docs](https://github.com/openwebdocs/project/issues/157) 34 | - What else? (ARIA-WG??) 35 | 6. Charter revision proposal 36 | - By Daniel, with a goal to be more description of the CG's practice (so far) 37 | - https://github.com/w3c-cg/webdocs/pull/6 38 | - Open to suggestions (or rejection!) 39 | 40 | ## Notes 41 | 42 | ### About last meeting 43 | 44 | Florian: we now have an issue about what we discussed last week: https://github.com/w3c-cg/webdocs/issues/1 45 | 46 | Patrick: will send this to Taylore on my team since she can be a good contributor to this. 47 | 48 | ### Security Docs 49 | 50 | Will: Going to talk about the work in SWAG. Have some slides. 51 | 52 | Will: The WebDX group a survey on MDN in 2023 on the State of Web Security and web developers understanding of it. 53 | 54 | Will: 69% of web devs found sec threats to be very challenging to understand 55 | 56 | Will: Secure the Web Forward workshop. Florian presented state of MDN docs. Reference docs are okay, guides, how-tos, are lacking 57 | 58 | Will: As APIs change, reference docs get updated, but guidances often is left behind. This happened with CSP recommendations and guidance, for example. 59 | 60 | Will: We then created the SWAG CG. Document Security guidelines for developers. For people building websites and for people building libraries. So two audiences, they sometimes overlap 61 | 62 | Will: We're developing a set of guidelines for both audiences. 63 | 64 | Will: SWAG has been helpful to produce docs for MDN Web Docs. Getting expert review and help to understand things. Brings confidence to the security guidance we want to give in the docs 65 | 66 | Will: We complete rewrote the CSP guidance, working on a series of docs on attacks 67 | 68 | Will: OWASP is hard to get into, assumes a lot of knowledge. Trying not to duplicate OWASP, starting earlier and pointing to OWASP for the gory details. 69 | 70 | Will: Next steps: Threat modelling: its often abstract, we want to make it quite practical. 71 | 72 | Will: Web sec fundamentals checklist 73 | 74 | Will: Web Auth guidances 75 | 76 | Will: Would love to have more SMEs engaged. 77 | 78 | Will: SWAG is probably going to wind up at the end of the year. Suggestion is to move it to the Docs CG 79 | 80 | Patrick: Hard to find people to do stuff for free 81 | 82 | Chris: Yeah, I have experienced this too 83 | 84 | Will: There is a lot of gate keeping going on. 85 | 86 | Florian: making a parallel with web components. Big companies are empowered to do this because they feel they can invest and have the time to get into it. Smaller orgs don't have the time. Might hold true for many aspects of the platform. As documentarians of the platform, we can help change this. 87 | 88 | Francois: the SWAG CG was partly made to attract these people. If SWAG gets folded into Docs CG, that might make it harder though, as Docs is more general. It's not specific to Security, or Web components. 89 | 90 | Florian: yes, on this group to figure out. 91 | 92 | Francois: We now also have SING, it includes threat modelling for web developers. https://www.w3.org/2024/11/security-ig-charter.html 93 | 94 | ### Feedback sources 95 | 96 | Chris: Use the socials for feedback 97 | 98 | Will: Drafting a survey for security docs, would love to qualitative research. Need to understand the "Why"- Questions. 99 | 100 | Florian: Let's try user interviews and report back to this CG how it went. 101 | 102 | ## Action items 103 | 104 | - Will to create an issue on the Docs CG repo to capture information on the Security Docs project 105 | - Florian and Will to look into Web Components content outline and give feedback to WCCG with the goal to invite for a follow-up conversation as well as onboarding new MDN contributors from the WCCG. -------------------------------------------------------------------------------- /meetings/2025-05-06.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG call, 2025-05-06 2 | 3 | Present: Florian Scholz, Lola Odelola, François Daoust, Justin Fagnani, Will Bamberg, Eric Meyer, Jonathan DeWitt, Jonathan Neal, (several others who joined later) 4 | 5 | Chair: Florian 6 | 7 | Note taker: Will 8 | 9 | Joining info: 10 | 11 | To join the video meeting, click this link: https://meet.google.com/jdp-xvka-hyk 12 | Otherwise, to join by phone, dial +49 40 8081617306 and enter this PIN: 544 514 889# 13 | To view more phone numbers, click this link: https://tel.meet/jdp-xvka-hyk?hs=5 14 | 15 | ## Agenda 16 | 17 | 1. Welcoming more new folks 18 | 2. Web Component docs 19 | - Issue: https://github.com/w3c-cg/webdocs/issues/1 20 | - Interpreting the survey for documentation needs https://2024.stateofhtml.com/en-US/features/web_components/ 21 | - webcomponents.guide 22 | - MDN docs: https://developer.mozilla.org/en-US/docs/Web/API/Web_components 23 | 24 | ## Notes 25 | 26 | ### Web Component Docs 27 | 28 | - Issue: https://github.com/w3c-cg/webdocs/issues/1 29 | - Interpreting the survey for documentation needs https://2024.stateofhtml.com/en-US/features/web_components/ 30 | - https://webcomponents.guide/ 31 | - MDN docs: https://developer.mozilla.org/en-US/docs/Web/API/Web_components 32 | 33 | Justin: vanilla versus using a library is a big issue in WC world. 34 | 35 | Lola: MDN usually documents vanilla, not frameworks. But in many places MDN needs to refer to frameworks, because most people use them through frameworks (e.g. WebRTC). 36 | 37 | Justin: WC are perceived as competing with frameworks like React. WC are mostly developed through libraries, and when we point people at the low-level it looks really bad compared with React. 38 | Libraries want common conceptual low-level docs that we can point to from the library docs. 39 | 40 | Florian: it's hard to keep up with framework docs. 41 | 42 | Will: It has not been successful to document frameworks on MDN. How much are vanilla WC docs directed at framework authors vs. web developers? 43 | 44 | Justin: small but vocal contingent want people to be able to write vanilla WC, without dependencies. Vast majority use frameworks. There is a base level of conceptual documentation that doesn't belong in the spec but could well live in MDN (e.g. shadow DOM). Vanilla WC features are still available in WC frameworks, so can still be useful to FW users. 45 | 46 | Justin: https://www.webcomponents.org/introduction was the original site for WC, and still has a lot of juice. https://github.com/webcomponents-cg/docs-and-guides/blob/main/plan/outline.md is an outline for a new site that hasn't been created yet. Docs for Lit would like to link out to somewhere like MDN for conceptual docs such as shadow DOM. 47 | 48 | Justin: someone could use a custom element from Lit, but not need the Lit docs to understand how to use it. So the "using web components" docs can be framework-agnostic. 49 | 50 | Jonathan: Frameworks sometimes experience the same thing. ShadCN users use a plethora of React components with their own API voices and gotchas. ShadCN picks the most similar and smooths over the styling. 51 | 52 | Lola: on MDN we're mainly documenting _writing_ WCs, not using them. Is part of the request that _using_ WC documentation should live on MDN 53 | 54 | Florian: https://diataxis.fr/ is a model for writing documentation. Four sectors, reference/how-to/tutorial/explanation. Helpful in coming to an outline, and we can see that many of these sectors are under-represented on MDN. 55 | 56 | Justin: not sure if appropriate for MDN, but want a marketing page for WC, not just users and developers, but decision-makers. High-level description of what they are and why you might want to use them. 57 | 58 | Lola: would be hesitant to create marketing in the same way that, say, React has marketing, but explaining the motivation for a tech to decision-makers might be different. 59 | 60 | Florian: Taylore quote from https://github.com/w3c-cg/webdocs/issues/1#issuecomment-2830416341: marketing in the sense that web devs don't have a well-explained justification for using WCs outside a framework. 61 | 62 | Will: "marketing" on MDN in the sense of giving explanations for why a web platform feature is useful, is fine on MDN, we do this all the time, otherwise the docs are incomplete. 63 | 64 | Florian: next steps are to assess Justin's input here and the outline, compare with the survey and see whether the outline seems like it will address the issues. 65 | 66 | Lola: in an ideal world, how would these docs interact? Would you just have docs for framework and link to MDN, or would there be some other docs? 67 | 68 | Justin: we maintain lit.dev and have a section on shadow DOM. we have two links near the top that do to dev.google.com (web.dev). Would like MDN to have the best shadow DOM doc, and link there for the details. 69 | 70 | Lola: Is there some initial contribution you could make to MDN to make e.g. the shadow DOM docs be as good as possible. 71 | 72 | Justin: yes, a collaboration with the MDN folk would be awesome. MDN folk can help us understand how to contribute to MDN. 73 | 74 | Florian/Will: We're happy are happy to help with that. 75 | 76 | ### Next steps 77 | 78 | - Meet with WCCG folks again to discuss more (either in Docs CG calls or separately) 79 | - Develop a content outline that takes into account diataxis, as well as needs identified from the survey 80 | - Look at the docs from the perspective of two audiences: people writing custom elements from scratch, and people using a library like Lit to integrate WCs. -------------------------------------------------------------------------------- /meetings/2025-10-07.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG call, 2025-10-07 2 | 3 | Present: Florian, Meyerweb, Dipika, Estelle, Lola 4 | 5 | Chair: Florian 6 | 7 | Note takers: Estelle 8 | 9 | ## Agenda 10 | 11 | 1. State of HTML Survey results 12 | 2. TPAC 13 | 14 | ## Notes 15 | 16 | ### State of HTML Survey results 17 | 18 | Shared Lea Verou's slide deck 19 | 20 | - https://docs.google.com/presentation/d/1hdmn7o5iDcjt6nk7QeGL5onzqok1lN-qzgMkGCfknhY/edit?slide=id.p#slide=id.p 21 | 22 | 6,000 respondents. Too many surveys, so generally fewer responses, but this got a lot of responses. 23 | 24 | The analysis is ongoing. Slide deck is a "first look". 25 | 26 | Looked into "educational pain points". Survey results included 402 points in this area. Categorized into more than 13 categories. One was "conflicting advice" among other things. Accessibility was the largest group. Someone, likely us, needs to do a proper analysis of these pain points. 27 | 28 | Lola: Is interested in looking at this. Does it make sense to meet up on this with WebDX CG? Are these freeform or select list? 29 | 30 | Florian: I believe they were freeform and categorized, but need to double check. The last slide is a link to the data analysis doc, and Florian has access. Access is granted by Lea Verou. 31 | 32 | Screen share of CODA view or results. May be able to research to share during either the next call or the one after that. 33 | 34 | Lola: Looking forward to an answer to my questions in a few weeks. Do we want to work on these areas? anything we want to do based on this data? 35 | 36 | Florian: DocsCG issue on web components can provide some insights. Can help indicate what type of reference docs we should invest in, and even areas to consider for funding requests. As a platform, we've invested in features and we should invest more in documenting those features. 37 | 38 | Dipika: When we started this CG, one of the ideas was that we could work with developers who will partner with us on documentation. They can identify issues and we can invest resources. This is a good indicator of how the community feels about docs. 39 | 40 | Florian: Agree. User interviews is useful. Open Web Docs is actually planning on doing that for the security docs. We can report back on how that went. Would be good to do this on a regular basis. 41 | 42 | 2025 data does include some information on web components similar to 2024. Yearly big surveys demonstrates where the needle has moved. 43 | 44 | Lea is still analyzing it. She's on the webdx calls. she's interested in other use cases for this data. Us, as techwriters, is another use case. 45 | 46 | 47 | ### TPAC 48 | 49 | TPAC is in a month. Two more Doc CG calls before TPAC 50 | 51 | - Pre event: https://ti.to/ntt-db/kobe-developer-meetup 52 | 53 | Estelle and Lola are giving a talk at the event. 54 | 55 | 56 | - We have three Docs CG sessions: 57 | - General session 58 | - Conversational docs session 59 | - Explainer workshop 60 | 61 | - Other sessions: 62 | - ACD meeting 63 | - Meeting with Web Components 64 | - Meeting with Authentication Adoption CG 65 | 66 | General session: maybe a good time to look at the group's charter. Also discussing how conversations with AI/Chatbots effects our work and the landscape. 67 | 68 | Lola: explainer workshop needs to have pre-determined goals. What do we want to achieve during that workshop. Generally, TAG members spread out to attend all the meetings, but there may be 3 people in this session so it needs to be tight. 69 | 70 | ACD may or may not be discussed in the ARIA working group. Main updates will be from Matt King. 71 | 72 | Florian: Will, Estelle, and Florian will be there and will likely spread out to attend more than one session at a time. It is going to be a busy week. 73 | 74 | In the next two sessions we should brainstorm the explainer workshop and the other two sessions we are going to host. We may change things, but we should be well prepared; work out the contents of the sessions. 75 | 76 | Lola: should we do that now? 77 | 78 | Florian: For general session: a recap of how the kickoff went; what worked well what didn't. Reviewing the charter. It's got a lot in it. Was it too ambitious? Let's look at what's possible and create a 2026 plan. We might have guests interested in documentation. We should talk to them about what their doc needs are. It was good to have web components group in our meetings. Would be good to get more feedback like that. 79 | 80 | Conversational docs session: nothing to present on this right now. 81 | 82 | Lola: Since Dom was the cheerleader for this. Should we ask him. 83 | 84 | Florian: Dom is going to be very busy, but will ask if he can lead or at least kick off the session with some thoughts. 85 | 86 | Lola: Patrick has been thinking about this. Put Lola in touch with Aaron Gustafason. Would be good to get them to be active participants. 87 | 88 | Florian: At i/o in berlin there was a lot of talk about MCPs. Not sure about the impact of MCP on day to day work. Will talk to Dom. If it doesn't come together, maybe we don't need to do this session. 89 | 90 | Florian: The explainer workshop: we did the exercise of going through a few explainers. This session should be about what DocsCG brings to the table when reviewing explainers. Is there a list of checkpoints? Are we the correct vehicle to tell them they haven't met the explainer requirements. 91 | 92 | Lola: we are professional technical writers, and we should use our experience as pros. We are different from the TAG. Some TAG feedback is non-technical stuff that could be DocsCG feedback. Doing a tech writer review would free up the tag to focus on the technical aspect of the feature discussed instead of focusing on how it's presented. We can also say we don't want to review explainers. 93 | 94 | Florian: We should discuss the process we could implement, like when does this group review explainers, expectations, etc. 95 | 96 | Action: Florian to ask Dom about co-leading the AI Docs CG TPAC Session. 97 | -------------------------------------------------------------------------------- /meetings/2025-09-09.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG call, 2025-09-09 2 | 3 | Present: Florian, Estelle, Lola, Vadim, Eric, Patrick, Francois 4 | 5 | Chair: Florian 6 | 7 | Note takers: Estelle 8 | 9 | ## Agenda 10 | 11 | 1. Intros (if necessary) 12 | 2. Explainer horizontal review checklist proposal by Lola https://github.com/w3c-cg/webdocs/issues/21 13 | 3. New explainers we could review 14 | - https://github.com/w3ctag/design-reviews/issues/1146 15 | - https://github.com/w3ctag/design-reviews/issues/1147 16 | - https://github.com/w3ctag/design-reviews/issues/1148 17 | 18 | ## Notes 19 | 20 | ### Intros 21 | 22 | - No intros needed 23 | 24 | ### Explainer horizontal review checklist 25 | 26 | **Florian:** Last session we reviewed 3 explainers. We want to be more structured about it. Lola has prepared a checklist see https://github.com/w3c-cg/webdocs/issues/21 27 | 28 | **Lola:** 29 | 30 | - inspiration from privacy and a11y groups. They have list available to spec authors so they can use when writing. 31 | - based on conversation from 2 weeks ago, every review should use the same rubric, and staying on what we should be focused on (documentation rather than the tech). Does it meet the requirements of what an explainer should be be? Open for additions/deletions. Reading code example as a way to know if the content makes sense to developers. Section on assessing the code examples: do the code examples explain how to use the feature. 32 | - First time accessibility concept: can someone outside of those involved understand the content the explainer is explaining? Two minds: 33 | 1. The explainer should be written for those who don't know the space. The spec written assuming the reader does know the space. If we assess by how accessible they are to readers. however, most don't meet this. Good explainers include definitions on terms, etc., 34 | 2. If we include this, it may be more work as most explainers don't meet this suggested requirement 35 | - Conversation: is this something we should have? 36 | 37 | **Florian:** 38 | If there's no a11y for first readers, there should be links for the reader to find more information. when it's a new concept to the reader, having links to material on the topic even though it was not web related was really helpful. Was able to gain knowledge about compute pressure from non-web related links. 39 | 40 | **Patrick:** 41 | Maybe instead of "first time reader" it should be "first read by a tech writer" - people with some knowledge and experience writing, rather than none. 42 | 43 | **Florian:** 44 | translation from tech into documentation. if TAG can't understand it we have a problem. 45 | 46 | **Lola:** 47 | It will be read by us, TAG, privacy space people, accessibility people. Should be readable by people in all those spaces. Everyone is technical, so maybe be more specific in our language about how technical. Maybe making sure there are resources, like a "what do I need to know" section. 48 | 49 | **Florian:** 50 | I guess we can be confident and say if a web docs tech writer can't understand the explainer then there is a problem with the explainer. 51 | 52 | **Lola:** 53 | if it's universally applicable? There are some very preliminary/incubation explainers. those will not be as fine-tuned as explainers for tech that is better supported / further along. 54 | 55 | **Florian:** 56 | You're right. There's not a lot in the incubation level explainers. 57 | 58 | **Patrick:** 59 | Further along? by definition, an explainer is not implemented 60 | 61 | **Lola:** 62 | often times the specification is much further along. Incubation vs. something with implementers is very different. For example, the age verification digital credentials APIs. Compared to proofreader API, but are not implemented, but one is hot so the explainer is further along. 63 | 64 | **Patrick:** 65 | We should spend the same amount of effort on each, not based on which step (incubation v. implementation) the process is on. 66 | 67 | **Lola:** 68 | digital credentials API is way past incubation (developed in the Federated Identity Working Group: https://www.w3.org/groups/wg/fedid/). Things are still being defined. In TAG we don't review if we don't have time / can't be useful / trust that team is working in the spirit of the web and we don't understand well enough to review. 69 | 70 | **Florian:** 71 | Add to our checklist / onto lola's issues that we can always skip an explainer. If it's too early, or other valid reason. 72 | 73 | ### New explainers to review 74 | 75 | **Florian:** Looked at design review repository and saw 3 new explainers. 76 | 77 | Proofreader API: https://github.com/w3ctag/design-reviews/issues/1146 says it's early 78 | https://github.com/webmachinelearning/proofreader-api/blob/main/README.md has code example and goals 79 | 80 | **Lola:** 81 | internationalization was not included in the rubric. the proofreader explainer would require that. the examples are all in american english but this should have a review by internalization team. 82 | 83 | **Lola:** 84 | should this include a11y section? 85 | 86 | **Patrick:** 87 | my experience is that proofreading is all javascript. i don't think there is an interaction with the dom tree. 88 | 89 | **Lola:** 90 | gives the developer tools, but doesn't output rendered 91 | 92 | **Florian:** 93 | can add html semantics manually. that's not part of the API so not in the explainer First explainer looks solid. 94 | 95 | Second explainer is a comment regarding FedCM- https://github.com/w3ctag/design-reviews/issues/1147 96 | 97 | **Florian:** 98 | I just reviewed FedCM so am familiar, but this mini explainer is very mini 99 | 100 | **Lola:** 101 | I shouldn't have to read a thread to understand what an explainer is saying. 102 | 103 | **Florian:** 104 | typically if something like this ships and this is the provided 105 | explainer, a lot of research work will need to be done by the tech writer in order to get the context and the idea of the change. 106 | 107 | **Lola:** 108 | give us an actual document. should be in an accessible repository. should be with working group, but sometimes it's with the browser, good to have something to point them to say follow the process. 109 | 110 | **Florian:** 111 | what would we do with a not-good-enough explainer. Do we tell the author? 112 | 113 | **Lola:** 114 | that's why it's good to have a non-public repo. we don't want to give spec authors more bureaucracy. everything tht comes in design review should be reviewed. should ask the authors of the explainer of explainers. 115 | 116 | **Florian:** 117 | let's discuss how we handle feedback in the meeting in two weeks. 118 | 119 | Third: Google explainer -- https://github.com/w3ctag/design-reviews/issues/1148 120 | 121 | **Florian:** 122 | some vendors have repos with a list of their explainers. 123 | this is a real explainer but doesn't have any code examples. 124 | 125 | **Francois:** 126 | odd this is that this looks more like a bug than something needing an explainer. from a process perspective, when is going through this process needed. looks like something that could be fixed by working group itself 127 | 128 | **Florian:** 129 | not every bug fix to a spec gets an explainer. what is the bar to requiring an explainer? does every new idl addition require an explainer? 130 | 131 | **Lola:** 132 | sometimes people put explainers that look like bug fixes, but we review it and say "yeah, it's good" but we can say "we're not reviewing this" as it's not a new feature or adding a feature. Do we see anything in this explainer that would require documentation updates? Our rubric could be "if it impacts documentation". If yes, then we review. if no, we let it go. 133 | 134 | **Florian:** 135 | There are some compat concerns, so that hints that there may be some docs involved. 136 | This has been a worthwhile exercise. We may come to structure and recommendations at some point. 137 | 138 | **Lola:** 139 | do we want to set a timeline or goal? 140 | 141 | **Florian:** 142 | we have 4 more sessions of this meeting before TPAC, when we'll meet with the TAG about this. If we keep reviewing 3 every two weeks, it will lead to a more informed discussion at TPAC. TPAC is the deadline where we can discuss in person and determine our role wrt explainers. 143 | -------------------------------------------------------------------------------- /meetings/2025-07-29.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG call, 2025-07-29 2 | 3 | Present: Lola, Florian, Estelle, Patrick, Vadim, Jeffrey Yasskin, Eric, Francois, Alexandra 4 | 5 | Chair: Lola 6 | 7 | Note takers: Florian, Patrick, Francois 8 | 9 | ## Agenda 10 | 11 | 1. Welcoming more new folks 12 | 2. [Explainers](https://w3ctag.github.io/explainer-explainer/) (joined by Jeffrey & Matt) 13 | 14 | ### Explainers 15 | 16 | - Lola: Let's talk about the explainer process 17 | - Lola: Docs CG could own this document / the process 18 | - Lola: Jeffrey is here, TAG co-chair, editor of the explainer explainer with Matt Atkinson 19 | - (round of introductions) 20 | - Jeffrey: What is an explainer? The TAG encourages folks to write up an explainer as a first exploration for an idea. Not yet specific solutions like IDL. In practice a lot of features get designed without an explainer, and so it gets written more like after the fact 21 | - Florian: how does this compare to the RFC process? Many open source projects, or standards orgs do requests for comments. Is an explainer sort an RFC for the web platform? 22 | - Jeffrey: meant to focus more on the use cases. In Python, the PEP process is similar to that. A lot of those are solutions focused. goal of explainers is to be more opened to different solutions. Doesn't always work out this way though. Teams usually have solutions in mind. 23 | - Jeffrey: we also get proposals to solve a problem, and it turns out there's no solution. The goal of explainers is to get people to be more opened about alt solutions. 24 | - Florian: would you say that explainers have no status? One thing we explore here is they're outdated, or come at the wrong time, or after the fact. It's usually very unclear to me where they sit in the process. With RFCs it's usually more clear. 25 | - Jeffrey: a lot of RFCs are the proposal document, and they live until the feature gets into the product. The RFC is the only description of what has been changed. On the web we have specs. So there's a discussion about what we do with explainers after that. 26 | - Jeffrey: I think Alex Russell proposed explainers originally. Thinks explainers should live forever. I think this is a mistake, and I've been advocating for the explainer text moves into the spec. No consensus on this yet. 27 | - Florian: if it's an ever green document, then how does it differ from the spec, docs, etc. 28 | - Jeffrey: On the TAG, when the spec has shipped, we say the explainer should be maintained/updated. Answer is to usually update MDN instead. 29 | - Lola: part of the issue with that 30 | - Francois: I note the lack of clarity about the status of an explainer unfortunately also exists for the spec itself from time to time. Example: WebRTC identity, which is essentially abandoned. Standardization can be a mess 31 | - Jeffrey: Implementers require specs to be updated but not explainers 32 | - Lola: What are the expectations of owning this document? (vs the process). Does it make sense for the Docs CG to own the process at all? 33 | - Jeffrey: Should be co-owned rather than transferred. Having the Docs CG co-own this would bring a good writing perspective. 34 | - Jeffrey: There are pieces like "alternatives considered" which might be bit outside of the domain of this group but use cases etc. are good to get a review on 35 | - Mozilla explainer explainer: https://github.com/mozilla/explainers?tab=readme-ov-file#how-to-add-an-explainer 36 | - Lola: agree it should be co-owned 37 | - (no disagreement) 38 | - Lola: what are the Docs CG responsibilities here exactly? review when TAG reviews as well? 39 | - Patrick: Consulting this group is useful to write a better explainer. For this group is useful to know about a new explainer. Don't want to make the whole explainer process slower. So one more step added to this doesn't feel good. 40 | - Estelle: Agree. Shouldn't be a step or a blocker here. Should be here to provide guidance. We're not the TAG, so we can't provide these kinds of reviews. 41 | - Lola: It should be more like taking a step from TAG rather than creating a new step. Danger that this feels like a new step is being added 42 | - Jeffrey: Feels like you want to do a horizontal review here. Spec authors send their spec to multiple groups for check in their area of expertise: like a11y, privacy, TAG, security, etc. 43 | - Jeffrey: could be that Docs CG does a review for how well it will be understood, documentation quality, etc. 44 | - Alexandra: The Docs CG should own how to write an explainer, and horizontal review sounds good too. however, we need clarity on what the scope is here. Is the feedback on the quality of the doc? What is it that this group brings to the table exactly? 45 | - Francois: Tracking: WebDX would like to explainers to be trackable. Would allow a web platform feature to be tracked through its lifecycle. 46 | - Jeffrey: bikeshed has links to WPT, so specs could maybe also start linking to web-feature ids 47 | - Lola: Done some Privacy horizontal reviews. Discussions in meeting, reviewer has a questionaire, then leave their review on the issue. Maybe come back to group for extra discussion 48 | - Florian: 1/ Figure out what a docs horizontal review would be. What the questionnaire might look like. 2/ Look at the explainer's explainer and see whether there are things we'd like to improve. MDN has page types. For example, to write a page on a CSS property, you get an explainer that tells you how to do it. How can we help authors write better and faster explainers? That seems enough for a start. 49 | - Jeffrey: what is this group most interested in in explainer docs? 50 | - Florian: The use case is the most important one for me. 51 | - Estelle: What other features are most relevant to this one? That may be interesting to look at. Maybe a way to get fewer specifications written. Privacy and security considerations, I'd like them to be fleshed out, and documented so as to understand the thought process. Example of AppCache. Or just to make sure that people are aware and think about privacy. 52 | - Lola: There are some situations where linking to other things may be cumbersome, e.g., in the CSS space. The considerations section is meant to tap into this though. You need to explain what alternatives you've considered. 53 | - Jeffrey: We also write explainers for tweaks to existing features. 54 | - Lola: Sometimes, explainers can be quite short. Feature may be about matching some external update in an external spec. 55 | - Florian: About the size of explainers: new feature vs. enhancement of a feature. There may be different kinds of explainers. We may need to guide authors as well so that they can take a shorter route. This guidance is currently not given. Maybe it makes sense to categorize existing explainers. 56 | - Lola: I think that can come later when we're clearer on what we want from people. Sometimes, it can be an adjustment to an existing explainer. But we need to understand what we want in general from web feature authors. 57 | - Estelle: Having more words doesn't necessarily make a document more cumbersome. If we had templates for the different types of explainers, it would add words to the explainer's document but it would lower the workload on the author. Writing about privacy, security and accessibility is not explained in the explainer's explainer. 58 | - Jeffrey: It would be useful to have guides for these sections in specifications too. There's a specific category for features that focus on developers, but there aren't as many categories otherwise. 59 | - Florian: Breaking down between CSS and HTML features may not be needed. I'm more thinking about "Service Workers" vs. "an add-on to Service Workers". Probably something to investigate. 60 | - Lola: In some of the ones I've been reviewed, spec authors are quite good at mentioning the underlying spec or feature when there is one. We can also rely on issue tags. If it's an addendum, it may still be a large addendum. 61 | - Alexandra: What happens to explainers when the feature exists? Does it get melted into the spec? I wonder if the answer to that question impacts the way we look at the doc. 62 | - Jeffrey: We also do not have a document that describes what a spec should look like. The QA activity that existed a long time ago produced some documents, mostly outdated today. 63 | - Lola: We have also spoken about that in the TAG. A larger discussion is needed. People have their own workflow. A small change may impact people. 64 | -------------------------------------------------------------------------------- /meetings/2025-04-22.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG call, 2025-04-22 2 | 3 | Present: Florian Scholz (OWD), Estelle Weyl (OWD), Ollie W., Lola Odelola (lola's lab), Francois Daoust (W3C), William Bamberg (OWD), Daniel Beck, Dipika Bhattacharya (Mozilla). 4 | 5 | Chair: Florian 6 | 7 | Note taker: Lola 8 | 9 | ## Agenda 10 | 11 | 1. Introductions and kickoff for the W3C Docs CG 12 | - Welcome! 13 | - Round of introductions 14 | 2. Logistics: 15 | - Finding a time and schedule for calls 16 | - Current proposal: Tuesdays, 1 hour, every 2 weeks. 17 | - Determining a place for asnyc discussions 18 | - Current proposal: W3C Community Slack in `#docs-cg`. 19 | 3. Reviewing the charter 20 | - https://github.com/w3c-cg/webdocs/blob/main/charter.md 21 | 4. Preparing the first Docs CG call 22 | - Identifying a topic and inviting SMEs, web developers, ... 23 | - Web Components? See https://github.com/w3c-cg/webdocs/issues/1 24 | 25 | ## Notes 26 | 27 | ### Logistics 28 | 29 | Florian: Is current time ok? Current proposal comes from availability of OWD folks, I'm eager to hear what works for others, if this doesn't work. This TZ isn't friendly for Australia, East Asia or Pacific. Do We want an APAC friendly TZ? 30 | 31 | Lola: Who in those TZs can't join? 32 | 33 | Florian: Mike Smith, but I haven't heard from him about this. 34 | 35 | Will: Hamish as well. Multiple TZ wasn't massively successful before, it got confusing. 36 | 37 | Daniel: Looking at participants list, quite a few people aren't here. We can survey those people to find out if the time didn't work today or didn't work in general. 38 | 39 | Florian: I can send a question out along with the minutes 40 | 41 | Dipika: How do I gain access to the slack? 42 | 43 | Estelle: It works for me on my non-W3C email address 44 | 45 | Florian: I can send you a direct email. Are we okay using the W3C slack? Do we want to use the IRC? Matrix? I think it works well with SWAG and other community groups. Alright, I can't see any disagreement. 46 | 47 | ### Reviewing the Charter 48 | 49 | Florian: A few of us have already reviewed the charter, it's in a markdown file in the repo and in there you can find the mission of this CG and scope of work. If you haven't already, I would recommend you review the document as it's the working mode for this group. It seems like today there are lots of tech writers but I would love to work with Lola to reach out to spec authors, browser implementers, etc on topics we'd want to deep dive into. 50 | 51 | See https://github.com/w3c-cg/webdocs/issues/1 52 | 53 | Florian: Someone as already reached out from a web components group, they're actively searching for feedback into their technical writing and examples. I'd love to see more of this. It would be nice if we could take a look into the state of web components docs -- Will has- 54 | 55 | Will: I have opinions 56 | 57 | Florian: That could be the first topic of the next call, what we can be done to improve the material 58 | 59 | Will: For me it brings up the issues of adoption, Web Components is a good case study for it. 60 | 61 | Florian: Getting input from web developers is important because they can give feedback on the quality of documentation and can identify bugs, comprehension issues, etc which may explain lack of adoption. We're translating between spec and practical implementation, so web dev voices are importatant. 62 | 63 | ### Reaching out and inviting people to this group 64 | 65 | Lola: Do we have a strategic way for reaching out to web devs considering they're an underrepresented group? 66 | 67 | Florian: No but we have a big task ahead of us but I think stuff like having specific breakouts, actively inviting web devs. 68 | 69 | Lola: Francois do you have ideas? 70 | 71 | Francois: MDN would be better way to target developers, I'm used to reaching out to chairs and groups members. Web Components Group, HTML group would be good, Web Components have a breakouts group. 72 | 73 | Dipika: On our page we can list topic areas for which we're looking for input, listing input from various groups, blank spots would indicate that we're still looking for participation for that topic from a specific group. 74 | 75 | Florian: It would also be good to get input from first-timers so that we can understand how well the docs are written. So we also want to put out a call for inexperienced too. 76 | 77 | Will: Can we use the Web Components as a model for how we do things? Re: Web Components, what happens next? Do we spin up separate thread? Add standing agenda item? 78 | 79 | Florian: I'd propose inviting them to the call, someone else would look at wholistic state of Web Components, as a group we'd have an opinon ahead of call they're invited to, we'd share on the call. Then we take it from them. 80 | 81 | Will: So shall we take issues from GH, we can build out the GH issue template 82 | 83 | Florian: Exactly 84 | 85 | Dipika: It would begin with scoping - are we tackling whole area or specific area? We'd have mini groups within this group and sharing our workflow, we can share pitfalls, learnings, etc. 86 | 87 | Lola: In TAG we do design reviews, the submitters are required to give a high level overview of the spec they want to get review on. Minimum two people are assigned to review async. 88 | 89 | Florian: That's a good comparison. I don't want to create process before we get started, but letting people start issues with us sounds good for now. But after a year, a process like a documentation review similar to how TAG works would be really good. The other thing I've learnt from WebDX is the use of workstreams, having a general stream and research stream, I could imagine a workstream for web components and maybe that goes on for a while until we think it's good enough and then we pick another workstream, etc. 90 | 91 | Daniel: Maybe this is a little meta, this conversation has helped me understand better what this group is for. The way the charter is written is like we produce docs, but this conversation highlights it's more about helping other people create their docs. 92 | 93 | Will: Yeah, this conversation is like a triage. People ask for help and we look for people to do the work but most of the work happens offline. So this meeting is like triaging. 94 | 95 | Florian: Yeah, it's like assessment too. 96 | 97 | Dipika: This group can be the place to come to find people who can improve web documentation. 98 | 99 | 100 | ### Web Component docs 101 | 102 | Estelle: We definitely do need to figure out guidelines as we go along on what we want to work on. Web Components seems good but hasn't been touched in two years, it's not an active group. We'd have to figure out what kind of community. Eventually we'd want a form that indicates activity level, target audience, purpose, etc. 103 | 104 | Florian: I like when people write docs but in this case, the feedback we'd give here may be question whether this will be actively maintained at all? 105 | 106 | Will: The website doesn't look like it's had much activity but I don't know if the CG has. Another question is should this stuff live in MDN or elsewhere? Living in MDN means it will be maintained. 107 | 108 | Florian: Thinking of a plan is part of helping people think about these things. Maybe we should have this conversation with them and not about them. Lola and I should invite them to the next CG call in the issue. 109 | 110 | Estelle: When there's a project proposal, we should do some digging as well. I've written a lot on WC topics, but as I dig more, they've not been very active since starting in 2021, they seem to meet twice a year. The suggestion from Lola to do offline work to research, having a subteam who's done the research so that there's knowledge before we invest time into it. 111 | 112 | Florian: We should do more outreach to get more web components people invited to the call. We also need some folks to do some research into webcomponents.guide page to let us know the state of things, so that we're better informed. 113 | 114 | Estelle: Looking at the issue, we need more information on what they need. 115 | 116 | Florian: I will invite them to the next call. If you have other topics in mind, let me know. 117 | 118 | Estelle: Do we want to come up with questions we want to ask? What are you looking for? What is your goal? What do you need help on? 119 | 120 | Daniel: Who is your intended audience? 121 | 122 | Florian: Do you have an updating/maintenance plan for the writing you've shared? 123 | 124 | Estelle: What is your writing/commit process? 125 | 126 | Daniel: We should be clear that we don't need long lengthy answers, we just want an idea of needs. 127 | 128 | Will: What is the problem right now? What could a solution be? How do they think it relates to other sites like MDN? Where do we want the docs to be, do we want to extend webcomponents.guide or do we have an editorial position that docs live on MDN? 129 | 130 | Florian: Yeah, I think that feeds into maintainability 131 | 132 | Will: and discoverability 133 | 134 | Estelle: Another question is what are they looking for from us 135 | 136 | Lola: This is a bit much for the first interaction. We don't want them to be scared away. We should provide them with the list of questions that we will be asking so that they can come prepared. 137 | 138 | Francois: Might be worth looking into feedback from devs on web components as well, as in State of HTML survey: https://2024.stateofhtml.com/en-US/features/web_components/ 139 | 140 | ### Closing 141 | 142 | Florian: I'm hoping we'll learn more as we run this and hopefully over time we'll have a better process. The conversations we had today were quite inspiring and we'll get better as we do more and I'm very excited! If you have thoughts on how this CG should be operated going forward, please submit an issue or let us know in Slack! -------------------------------------------------------------------------------- /meetings/2025-12-02.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG call, 2025-12-02 2 | 3 | ## Agenda 4 | 5 | - TPAC Update 6 | - What should we focus on 2026 7 | 8 | ## Minutes 9 | 10 | Lola: Good to see everyone. A lot was discussed at TPAC. Three sessions: one general to talk about the Docs CG direction, one talking about AI led by Florian and Dom, and one about the Explainer explainer and whether we want to have ownership of that process. Invited Matthew Atkinson and Jeffrey Yasskin. 11 | 12 | …We decided not to take any part of the explainer process formally. If we want to give feedback, we're free to do that. Main reason is because of issues in terms of time commitment. Reviewing them would take up all our time and nobody here is funded to do it. But we can always give feedback. Especially in terms of translating things into terms web developers can understand. 13 | 14 | …In the general sessions, we assessed how things have been going and how things could go moving forward. The main concern I remember hearing was time commitment. We discussed taking the template of the WebDX CG and how they manage their calls. They pick two things to focus on and who's going to focus on each one. Two tracks: one for general DX stuff, and one for Baseline alone. It makes sense since a lot of people there are funded to work on Baseline. 15 | 16 | …We could have a track in our calls where things people are funded to document could be covered. The other track would be about general Docs CG stuff. We can iron things out in terms of how docs are developing, etc. There wouldn't be an expectation to do work outside of the meeting. 17 | 18 | Florian: I think it was a good outcome that we discussed the tracks. There's always a research and preparation phase, and then a writing phase. We're writing security documentation, but we still need review from subject matter experts as we execute the plan. 19 | 20 | …We have a research phase like when we have guests to this call, and we figure out a content plan. I think this two-track system kind of makes sense. It helps clarify when we invite people to the call, when we go to working groups, and so on. 21 | 22 | …It does put a bit of work on the chairs to get this going, but I think with security docs, it's shown that this can work. Practically speaking, for security docs we're in the writing phase. On the research track, we have some candidates but haven't picked one yet. 23 | 24 | Lola: Next on the agenda is a discussion about what to pick. Did you want to add anything about the AI session? 25 | 26 | Florian: There wasn't a clear outcome. We mentioned it's a difficult space and it's unclear how we can help. 27 | 28 | Patrick: Were there notes taken? 29 | 30 | Florian: Yes, there were. I’ll put them on Github soon. I’ll try to see if there are summaries I can post into the Slack. There was no groundbreaking thought like the two-track system. 31 | 32 | Patrick: On the idea of a two-track system where we invite experts, I think it’s a wonderful idea. Bringing people here helps form more of a community around the Docs CG. 33 | 34 | Florian: Agreed. I was in the performance WG session as an observer and they were thinking about re-chartering, and had a deliverable of a web performance primer. The one they have is very dated, and should be retired and replaced. I said yeah, you can always collaborate with us. They were quite open to this. We could add them to our agenda and assist with figuring out what's needed. Sometimes it comes down to going to the WGs. 35 | 36 | Patrick: I see it as this being the invitation phase, where we can put out a call for people working on performance documentation. 37 | 38 | Dipika: I’m curious to understand how it works in the SWAG group. I imagine we would invite certain folks and there would be meetings to discuss, but in the introduction we could set expectations and requirements. Going forward, are the discussions async on Slack and in docs, or do people need to show up to meetings? 39 | 40 | Florian: I think it’s better to talk face to face, or on calls. The weekly calls are a reminder to those experts that we’re here and writing docs and need experts to look over our shoulders and make sure we’re writing the right things. I think everyone in SWAG sees the value in that. 41 | 42 | Lola: To add to that, in SWAG when I was in it and in TAG, the meetings act as a checkpoint. They update the members of the meeting, but if you have work to do for the next meeting, you know you need to do things in that time frame. When doing remote work, it’s 4easy for things to get lost in the pile. 43 | 44 | Florian: Another benefit is that as we write about these technologies, there's a bit of Q&A for the spec and the working group. 45 | 46 | Lola: Next is what we should focus on in 2026. Would like to hear from everyone about what ideas they might have for places we can be useful. Florian, I think you mentioned Web Components and Views. 47 | 48 | Florian: More generally, I think the two-track system and more connection into working groups is my meta-goal. 49 | 50 | Lola: You attend the Web Views group, right? 51 | 52 | Florian: Yes. I think it's more talking about documentation with these groups and how good documentation helps with adoption. 53 | 54 | Dipika: Do the SWAG experts also include web developers? 55 | 56 | Florian: They're definitely under-represented. 57 | 58 | Dipika: One thing I'd like from this group is more developer outreach, going directly to the consumers of the documentation. FInding out their pain points and what they need. It will help us. 59 | 60 | Lola: Agreed. We should do that and it's something we've discussed. A few things to be aware of is that when we ask developers to participate, especially more than once, if they aren't funded, it will be very difficult for them to justify the time. I think outreach to developers specifically may look like conferences or things outside this group where they already are. 61 | 62 | Florian: From SWAG, what we're trying is a survey to gather a tiny bit of data and also volunteers to work with us. Don't know if it will work. Depending on how that works in the next year, I’ll reoprt back here and would hope we could do something similar. My hope is that it would be possible to get an hour here or there. 63 | 64 | …I have some friends who do user testing and they invite people into a room and all that. I need to figure out how to do similarly in the virtual world. 65 | 66 | Lola: I think about this group as a hinge that can straddle both the developer and standards communities. User testing would be great, going to developers we know. MIght be easier for us than other groups. 67 | 68 | Florian: In a sense we're translators between groups. 69 | 70 | Lola: Something that came up at TPAC was a desire to focus on things we have funding for. It's easier that way. SWAG has funding to work on documentation. There is some funding for writing about Baseline. 71 | 72 | Dipika: We're still planning MDN's 2026 roadmap. If anything surfaces there, I can bring it to this group. 73 | 74 | Florian: OWD is funded on security documentation well into the year. We have another but I don't know what it will be yet. We can look to see if OWD can take things on using our general funding. 75 | 76 | Lola: Speaking of the research track, what do we want to research? Web Components? Are there other areas we want to look into? 77 | 78 | Florian: I don't think we'll decide that today. 79 | 80 | Lola: I mean in terms of ideas, things we might seek out funding for. A rough idea of directions we could go. Web Components is easy; we've already done work on it. It makes sense if we want to continue down that path. 81 | 82 | Patrick: Anything soon to be Baseline widely available, and anything in Interop. If there are gaps, I mean. A slightly bigger and more uncertain is things on AI devices. If AI gains more traction in the standards world, then we might need more documentation like guides and tutorials. There is one guide for the Summarizer API, but maybe there needs to be an overarching “AI on the Web” thing. 83 | 84 | Lola: I think that’s a good shout in terms of what proposals we’re seeing in TAG. For the most part it hasn’t been too controversial. A few things, but nothing that’s been “this can never happen ever”. So we should keep an eye on this. Having AI on the Web documentation is necessary, because of how developers are using AI. We need to consider the flip here. Usually we rely on standards, but here developers are already doing this, so having guides on how to do it safely makes sense. 85 | 86 | Florian: There's also WebNN, which is much more low-level. The question is always how much documentation we should write about low-level concepts. 87 | 88 | Lola: Sounds like we want to still figure things out. What are the blockers to things we want to work on? I'm hearing funding. Any others? Potentially time. 89 | 90 | …How long should we wait, and what do we wait for to know we should start researching a certain thing. 91 | 92 | Florian: I need until January. 93 | 94 | Lola: Okay. And Dipika, you'll let us know about MDN? 95 | 96 | Dipika: Yes. 97 | 98 | Lola: Cool. Any other business? 99 | 100 | Patrick: On reaching out to web developers, 100% agree they're very time-constrained. And even when they do participate in standards, it can be very intimidating. I like the idea of going where they are. Reach out to event organizers to see if we can be there, maybe have a short workshop or open hours or a board to post questions or something. I see this at CSS Day and Smashing Conference. It can be a very tactical, lo-fi tool. 101 | 102 | Lola: Thank you. Anybody else? 103 | 104 | (silence) 105 | 106 | Lola: Everyone gets back 19 minutes! Do we want to have a meeting in two weeks? 107 | 108 | Florian: I would say cancel. 109 | 110 | Lola: Objections? 111 | 112 | (silence) 113 | 114 | Lola: Happy holidays and see you all in 2026! -------------------------------------------------------------------------------- /meetings/2025-11-10-tpac.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG and W3C TAG session at TPAC, Kobe, Japan, 2025-11-10 2 | 3 | Attendees: Jeffrey Yaskin, Dan Appelquist, Florian Scholz, Will Bamberg, Hadley Beman, Lola Odelola, François Daoust, Brian Kardel, Rachel Andrew, Estelle W., Matthew Atkinson, Vadim, Chris (Chomium, PNG) ? ? ? 4 | 5 | https://www.w3.org/events/meetings/cb1431ba-d0d5-461c-9e5e-aab4c2da403f/ 6 | 7 | Slides: https://docs.google.com/presentation/d/1Gxk2-8_Rm1HDgSBeRUQHHtUDKalBKy8StlIuBGJ7BFA/edit?usp=drivesdk 8 | 9 | Florian: We'd like to talk about explainers... What we found is that explainer docs vary quite a lot... Could be a new feature.. Could be a new concept, an entire new spec, can be very overwhelming. We also found that "if we can understand it then we can write docs... but if we can't understand it then the explainer isn't very good." We've seen explainers being fairly minimal... We were wondering if the author doesn't care... then what's "our job" - are we the completeness police? 10 | 11 | Discussion questions: 12 | 13 | * Who are we doing this for? 14 | * What will be better as a result? 15 | * We want to be helpful, not yet another process item. 16 | * What parts of the explainer doc are we responsible for? 17 | * How does this fit into the overall reviewing process? 18 | 19 | Jeffrey: when, do you document things? 20 | ... 21 | 22 | BrianL: standards track? Do you exclude WICG thing? 23 | 24 | Will: In practice, no... not on MDN. Can be incubation as well. 25 | 26 | Hadley: when we first started asking for explainers, there was resistance because it's extra work. At the same time, I worry that if we go too far to make explainers useful in other contexts then we might make it even more work. People want to spent time working on their feature. Wanted to highlight that as a potential risk. 27 | 28 | Lola: Not talking about expanding explainers in any significant way. So far it's kind of been more like "is there scope to review explainers that lessens TAG's load and if there is what does that look like?" There's a checklist that I've proposed: 29 | 30 | > Explainer review checklist, proposed by Lola 31 | > https://github.com/w3c-cg/webdocs/issues/21 32 | > 33 | > Section completeness 34 | > * Code examples: 35 | > * Are they syntactically correct (at least plausible JS)? 36 | > * Do they illustrate use cases, not just API shape? 37 | > * Diagrams properly labelled (alt-text or caption) 38 | > * Links point to correct locations 39 | > * First time reader accessibility, i.e. can someone outside of the space understand what is being proposed and why?* 40 | 41 | Lola: not sure we [TAG] can avoid people being annoying... 42 | 43 | Florian: it's not the goal to be annoying.. unless annoying comes with some benefits... Use cases e.g. so useful. I think there are good benefits from writing a technical explainer. 44 | 45 | Vadmin: there is usefulness in this initiative (requiring one implementation) ... there are often no use cases and code examples. I know a few examples where explainer was a good source of docunentation for MDN. A well-written explainer really helps. There are examples where something has shipped in a browser and still no MDN article so it helps. 46 | 47 | Matthew: "what is an explainer and what's it for" - i liked the time about first-time reader accessibility. Why is it important? One of the key purposes from TAG pov is to help reviewers to understand the trade-offs that were made when something is being designed. Why are we doing it? what are we doing it? what were the trade-offs? Also: we would expect some things to move form the explainer to the spec... But some things would stay in the explainer (e.g. "we thought about xyz but decided abc"). I have had some feedback from APA - use of the term non-goals. I read it as "out of scope" .. is it more deliberate? 48 | 49 | Jeffrey: sometimes gets used as "hard out of scope." 50 | 51 | Hadley: "that's not what we're talking about and we're definitely not going to do that." 52 | 53 | Jeffrey: as TAG I would love people to review explainers... But the group should be doing things that further this group's goals. So what ensures that you can write documentation later in the process when you need to write documentation. 54 | 55 | Brian: In WICG, even before something is adopted, people create explainers. I don't know that everyone is great at writing one. A lot of people who write them would love immediate feedback. Maybe that's something that would help. Getting quick feedback would be very valuable. Most people are not technical writers. The earlier we get then corrected the better. If the DocsCG can do that, great! 56 | 57 | Lola: We're a small group... 58 | 59 | Rachel: question I had was around timing - I used to do all the chrome first docs... would quite often find that the explainer, spec and docs would be out of sync. We write docs when things go to Beta. If at that point, if the spec is different from the spec then it's misleading. 60 | 61 | Florian: I agree ... also we discussed the lifecycle of explainers. Merging with the spec might help with the lifecycle of it... MS have an index of their explainers with different statuses. In reviewing explainers we can bring in the lens of the web developer... that might help to shape. Process of reviewing... We need to take time to review on the calls... More help appreciated. We get through 5-6 a call... 62 | 63 | ... 64 | 65 | Estelle: instead of having DOCS CG go over it, would a TAG member be better to guide the explainer... maybe a mentor? If one person was assigned... 66 | 67 | ... discussion of how to get people quicker feedback ... 68 | 69 | Estelle: should we add guidelines for updating explainers... Should we add it to the explainer process to add it to explainer explainer? 70 | 71 | Matthew: it's in the explainer explainer... 72 | 73 | François: With specs we also have the problem with outdated info... We extract info into wpt ... some tests fail so you get insensitive to tests... Feedback loop. 74 | 75 | Chris: sometimes we make a live demo and then update the explainer to just link to that. Also what would trigger a re-review? 76 | 77 | Lola: spec authors are generally good at notifying when we should re-review. There is an incentive with TAG ,,, We'd need a trigger for automated check. 78 | 79 | Will: is there a general expectation that explainers are reviewed / kept in sync? 80 | 81 | Jeffrey: there's a hope. 82 | 83 | Lola: some implementers are better at doing so than others. 84 | 85 | Jeffrey: explainers have a more detailed lifecycle. Mozilla have a good example. Ideally the explainers are short... There are a couple of lifecycle points that would make sense to hook into. For Chromium it's Dev trial, origin trial, TAG review... For Mozilla and Safari I don't think there as many. 86 | 87 | Matthew: also where should explainers be put? Different orgs and groups have different practices. They can easily get forgtten. 88 | 89 | Jeffrey: about testing explainers: we don't have good ways of embedding external content since they are just markdown files... This is a good reason to encourage people to move code examples into the spec. 90 | 91 | Hadley: on the lifecycle thing we have tried to keep off the w3c process. However speaking as a chair, when arriving at a transition point, I arrive at the Process... We could add "you may wish to add an explainer, update the explainer." 92 | 93 | Dan: I raised the issue in the AB member-only repo to ask to make explainers a more formal thing. One of the original goals of the explainers was to make it easy to write something that's useful for developers next to your code, your spec. There are competing tensions. From a W3C process standpoint, and we're talking about Process in the AB, the TAG review does not appear in the Process. In the Process process, we're trying to figure out where the Explainer's explainer is going to fit. 94 | 95 | Lola: answering the key questions - actionable things.. a desire fot docs cg to do explainer reviews... a question that has arisen in this group... What does that look like in practice... Do we monitor the TAG review queue? Do we need to respond to people even if they haven't asked for review. 96 | 97 | Jeffrey: it's not only the TAG who gets to review specs and gets to feed back. Anyone could file issues... If Docs CG monitor the TAG design reviews we might be duplicating work. It's probably better for Docs CG to chime in earlier. When the explainer is submitted to the repo. They still get submitted before TAG review happens. If Docs CG watches those repos they could do quick review... doc quality review ... would save TAG time. I can point to those repositories... 98 | 99 | Florian: we've also found ourselves... having our own checklist... not looking at the technical details but more "how well is it explained." 100 | 101 | Estelle: if that happens the Docs CG needs to have a point where it [hands over] to TAG. 102 | 103 | Lola: leaves us when it gets to TAG? 104 | 105 | Estelle: I'm thinking "we've given feedback and they haven't fixed..." 106 | 107 | *discussion on why docs cg asked to proactive outreach* 108 | 109 | *are DocsCG reviews useful enough to be considered part of horizontal review?* 110 | 111 | Florian: sometimes when I have feedback on a spec it's too late... 112 | 113 | Hadley: lots of TAG reviews. 114 | 115 | Matthew: in APA sometimes the feature has shipped a year ago before we see it... It's a universal problem. Some work in the W3C team around incubation and adoption. How do we know what's important to review? 116 | 117 | Jeffrey: sometimes if you want to have an effect you need to go out and proactively seek... 118 | 119 | Lola: we don't look at things if they are missing significant sections... 120 | 121 | Dan: Jeffrey's suggestion to be proactive implies that things get discussed in specific places that can be watched, and we've had various cases where things came from individual repos. 122 | 123 | Jeffrey: I think we've fixed that. 124 | 125 | Bryan: There are cases where proposals get raised in issues. 126 | 127 | Jeffrey: That's right, we should push back on this when the proposal should need an explainer. 128 | 129 | Lola: If TAG receives a request for a review of an explainer that comes from an untracked repo, it could redirect to the Docs CG. 130 | 131 | Florian: What's the bar for creating an explainer? 132 | 133 | Hadley: Historically, that's whatever you want a TAG review for. 134 | 135 | Lola: example of webaudio... some groups asking for review for small changes... 136 | 137 | ## Next steps 138 | 139 | Florian: What are the places that we can observe ... let's observe for a while... and submit feedback to those places.. -------------------------------------------------------------------------------- /meetings/2025-11-11-tpac.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG General session at TPAC, Kobe, Japan, 2025-11-11 2 | 3 | Attendees: Simeon Vincent, François Daoust, Vadim, Lola, Florian, Rachel Andrew, Niklas Merz, Estelle, Alan Buxey, Micheal Wunderlich 4 | 5 | Lola: goals for this session: review progress. We formed earlier this year with lofty goals, do we still want them or different ones? 6 | 7 | Lola: each person to say something that's gone well and something that could be improved. 8 | 9 | Florian: something that went well: meeting with other WGs, especially Web Components WG. Should be more of talking to other WGs about the work they are doing. Also survey results on Web Components. 10 | 11 | Florian: not so great, we just met once and haven't followed up. Bandwidth issue, and it's hard for us to show up in random WGs. 12 | 13 | Estelle: what also was good: meeting up with other technical writers. Could improve on: bandwidth, finding time for the things. 14 | 15 | Will: I have been more involved in Security related documentation. I valued the discussion with Web Components as well. I think there's value there. 16 | 17 | François: haven't been able to spend time in CG. Main drawback is again bandwidth, but happy docs CG is around and has fresh energy to standards process. If you feel you don't have the standing to be involved we can help with that. 18 | 19 | Vadim: haven't been involved too much but noticed more discussions which is good to see. 20 | 21 | Lola: something that went well: our openness to explore the explainer process, looking for ways to be more integrated into the standards process. Good reception from other groups within W3C as well, e.g. TAG. What could be improved? TPAc would have been a great opportunity to do a breakout workshop on tech writing, how features go from spec to MDN docs. But this is a lesson for next time. 22 | 23 | Estelle: wish we had a way to communicate with WGs outside of meetings. 24 | 25 | Florian: yes, feedback loops go both ways. We like to know about the WG work but they also like to see our perspective and the perspective that we bring of the web developer. Explainer work is part of this but there is more. 26 | 27 | Will: e.g. in SWAG today, webappsec proposing process changes to help keep docs up to date. 28 | 29 | Florian: everyone is into ensuring the adoption of the things they are working on, and docs are a big part of that. 30 | 31 | Lola: we wanted to review the charter. 32 | 33 | Lola: item 1 in charter: plan and write new docs for web platform technologies. 34 | 35 | Florian: we do this generally in our work, OWD has a backlog/dashboard for new things that are missing: this speaks to "make sure ref docs are complete". For "identify needs for guides", we have done some analysis for web components but not written anything. This group doesn't always need to be writing the docs. 36 | 37 | Vadim: consider moving dashboard to Docs CG. 38 | 39 | Lola: if this is a direction we wanted to go in, there is a precedent for this in W3C of CGs that do work that isn't specs. 40 | 41 | Florian: dashboard is really rough but happy to relocate it. 42 | 43 | Estelle: same thing: it is part of our workflow but happy to make it more public. 44 | 45 | Will: SWAG CG is also a precedent for this. 46 | 47 | Vadim: would help to get non-OWD people involved in the CG. 48 | 49 | Simeon: interested in this from the perspective of browser extensions, improving the docs. 50 | 51 | Estelle: would this be in mdn/content or the dashboard/CG 52 | 53 | Simeon: don't know. Right now trying to figure out how browser extensions can participate better in standards process. 54 | 55 | Lola: so decided to move dashboard. 56 | 57 | Lola, item 2: "work with spec authors to define best practices for docs, code samples, IA". We haven't done this. 58 | 59 | Rachel: with spec author hat on, what were you expecting from spec authors? 60 | 61 | Lola: web devs do read specs, and tech writers need to understand them too and some specs (e.g. CSS) are more readable than others. 62 | 63 | Florian: we were thinking of DOM specs that are very hard to read (procedure-based) and don't include code examples. But if we don't know what this means we should clarify the charter item. 64 | 65 | Estelle: the explainer is in scope for this. We've made a start. 66 | 67 | Lola: item 3: maintain docs using approaches like docs as code 68 | 69 | Florian: also that repositories talk to each other (e.g. integrating webref into MDN). Integrated webref v7 into BCD. Maintenance is going on. There are more opportunities for us to follow up on here. 70 | 71 | Lola: this makes me think in our meetings we should have regular updates on work going on that's relevant to the charter. 72 | 73 | Lola: item 4: be a resource for resources: map documentation sources for web devs and invite them 74 | 75 | Florian: we have had web.dev present in the call. Still heavy on MDN. We see microsites like passkeys.dev. 76 | 77 | Lola: q for Rachel: is this group something your writers would be open to participating in? Is there alignment? 78 | 79 | Rachel: possibly. We have 2 sites, web.dev and developer.chrome.com. Alexandra was interested, others would be. Hard to make time though. 80 | 81 | Lola: some groups use the mailing list a lot, maybe we should provide email updates. 82 | 83 | Florian: would prefer GitHub issues. 84 | 85 | Florian: could be useful when we want to deprecate, so as to coordinate a message across sites. 86 | 87 | Vadim: do we have contacts at w3schools? 88 | 89 | Florian: yes, we could look into this. 90 | 91 | Lola: item 5: driving adoption, including interpreting dev surveys 92 | 93 | Lola: we did examine a couple of surveys and it was very fruitful. Accessibility was high on the list. 94 | 95 | Florian: surveys can tell us when people aren't understanding concepts, it's a signal to tech writers that there is work to do here. Tried to list pain points with web components that we should address. So continue to keep an eye on surveys. In SWAG we will also be running a survey and some user interviews to understand their understanding. Important to talk to both sides: SMEs and web developers. Would welcome web devs to join docs CG as well, to give us their feedback. 96 | 97 | Lola: Ensure documentation relevance, coordinate efforts to get outdated docs updated. 98 | 99 | Estelle: we do it in OWD, no through this group. 100 | 101 | Lola: again we should have an item in our meeting to discuss MDN activities and coordinate. 102 | 103 | Florian: for ref docs, vendors (Google and Mozilla) have tech writers who document new features. What's not tracked is existing docs that are not adequate. That's not coordinated or tracked right now and this group could be the hub for it. 104 | 105 | Estelle: Apple is documenting their stuff but only on their site. It would be helpful to get them involved. 106 | 107 | Lola: yes it would. 108 | 109 | Lola: with interop there is a lot of coordination between vendors. 110 | 111 | Rachel: some vendors want to put everything through legal which makes it hard. Many people write tech content but don't consider themselves tech writers. e.g. Smashing mag. Perhaps they might be put off by framing it as web docs. 112 | 113 | Lola: yes, if we can identify where people meet we could ask them to join. 114 | 115 | Florian: when we launched docs CG had some interest and there were people who showed up, who don't any more. Maybe ask them again what they want to get out of it and how it can be more useful. Maybe be more open to async communication. 116 | 117 | Lola: if we write agendas ahead of time we can advertise what's going to be in them. 118 | 119 | Florian: idea is that we have editions for different groups, and do analysis on each and capture results in the issues. But how do we inject ourselves into WGs? 120 | 121 | Lola: could help with this via TAG. Once a month might be too much but once a quarter might be doable. Then we would get 4 areas a year to analyse. 122 | 123 | Florian: but before that we have to know we have capacity. 124 | 125 | François: no process is needed, just go and talk to the WG chair and see if they want to come. Usually people are willing to come. 126 | 127 | Lola: APA is similar, attend other WG meetings to talk about accessibility. 128 | 129 | Lola: be a hub for web documentation when docs projects appear 130 | 131 | Lola: BUT: capacity. We had big dreams to help the Web Components, but one (very productive) meeting and no follow-up. We're a small group and we don't have capacity outside meetings. What can we do? Lighten our load? Look for more people? Look for more funding? 132 | 133 | Estelle: need to create a plan for communication, tracking, and follow-up. 134 | 135 | Lola: agree but even with processes, if the time is not there we can't do it. e.g. TAG, requirement is 1 day a week, and that's 1 day only TAG. What is our expected time commitment (if there is one)? 136 | 137 | Florian: SWAG is somewhat successful. think of it as a specialised docs cg. We are funded, we can move it forward. If we finish and are funded, we could work on web components. 138 | 139 | Estelle: maybe docs CG could be overarching group for SWAG CG. Worked on CSS modules alone. 140 | 141 | Lola: inspired by web components/webextensions/WebDX, if you get funding to work on a thing, you could alternate on the thing you are working on with the general meeting. 142 | 143 | Florian: WebDX decided to focus on just two things for now, 144 | 145 | François: work follows funding. 146 | 147 | Will: have talked before about SWAG in docs CG, and would be fine. But want a track of executing our current projects (security, whatever else) and one of getting and assessing and triaging new requests for docs. 148 | 149 | Vadim: it should be clear that it's possible to extend the scope when there are more resources. e.g. webextensions docs. Open to bringing new items if people bring 150 | 151 | Lola: explainers: people are into it but as Jeffrey said, if we don't get anything out of it we maybe should not do it. We maybe don't, but we might still show value by doing it. 152 | 153 | Florian: research/analysis is important or funding. Our STF application was based on a lot of research on web security documentation. Analysis could be the basis of a pitch. 154 | 155 | Lola: what is the appetite for doing explainers? Could help inform research, as we choose the explainers. But we can look at explainers anyway without having to review them. 156 | 157 | Florian: it's helpful to review things and make them better. Some explainers would be useful to read but not random explainers. It does help TAG but we're not TAG. 158 | 159 | Lola: as docs CG it's fine to say no. 160 | 161 | Estelle: we could do something partial nd not review every explainer. It would be good if explainer had a form listing the components that should go in the explainer ("not applicable" is an option for some). That would give us more consistency. 162 | 163 | Lola: sounds like a job for the editors of the explainer explainer, not for us. 164 | 165 | Florian: weird to go to giant vendor X and complain about stuff in their repo. 166 | 167 | Lola: if you're in W3C, then places that work goes on are open for people to comment. Explainers may not be on W3C repositories, but a lot of the people who participate are not members of the giant corp. 168 | 169 | Lola: sum up: 170 | 171 | - we want to refine the tangible work into multi-track, one track is research one is docs 172 | - maybe explainers but looking like no 173 | - moving dashboard into docs cg. 174 | -------------------------------------------------------------------------------- /meetings/2025-11-13-tpac.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG Conversational Docs session at TPAC, Kobe, Japan, 2025-11-10 2 | 3 | Present: Dom, FLorian, WIllB, Estelle, Francois, Roy, Alan Buxey, Nour Nabil, Takaaka Nishioka, Simeon Vincent, Mike Smith, Richard Ishida, Francois, Kadir Topal, Andrew Liu, Michael Pennisi, Dan Appelquist 4 | 5 | Florian: with AI, more devs are in sync AI conversations than reading or in Stack Overflow threads. Also more info appears in autocomplete or search engine results. 6 | 7 | Florian: less traffic in traditional knowledge sites like Wikipedia or MDN. Contextualized situational interactions instead. 8 | 9 | Florian: SO is a lot like an AI, in that it promises to answer very specific questions. But results are publicly visible and could be improved by other contributors, and was present as a common good. That's now a private experience, others don't get to see the answers (or improve them). MDN is a bit different but still sees a big effect. 10 | 11 | Florian: more content != more knowledge. AI must RTFM on behalf of its users. We have no insight into the context users have when they use AI, harder to provide tailored documentation for them. 12 | 13 | Florian: still "classical" writers but also "context curators" providing situational pointers: best practices, checklists, recommendations. 14 | 15 | Dom: risk of platform being frozen in the past due to training latency: Dead framework theory (Paul Kinlan). Risk of bad/old practices being reinforced - because training is statistical, so popular wins. So need to find the right way to feed best practices into coding agents. Could even use agents to push adoption of technologies to use the best practices. 16 | 17 | Dom: if we consider AI systems as a new target for documentation, with the theory that we can guide them towards a better outcome, then we need to understand their own limitations. For example, they have a very limited context window: the amount of info you can give them before they start hallucinating. How much do we want to invest in LLMs as a customer of technical docs? If we think they are customers, how do we adapt what we do to serve them effectively? Not just how we do it but how to deploy it in the real world. 18 | 19 | Alan: LLMs text proposal: the issue with LLMs is the context window. LLMs text is docs for AIs. 20 | 21 | Mike: is this something that is produced in parallel? As well as docs for humans? 22 | 23 | Alan: in parallel. 24 | 25 | Mike: why aren't the machines smart enough to understand the human-version? Isn't that the point? 26 | 27 | Alan: partly context window. You don't need all the other documentation. AI doesn't need informative text, only normative text. Can be less friendly, not include the stuff for humans. 28 | 29 | Estelle: if it only reads normative text, why not read specs? 30 | 31 | Alan: depends how the docs have been written. 32 | 33 | Dom: one of the values of LLM.text is that LLMs don't benefit from navigation or fluff. But we have seen problems whenever we've tried duplicating content. LLM.text addresses a narrow part of the problem. It doesn't address: how does an LLM get to the right answer. If we ask a chatbot to do something, how can we ensure it will use the techniques we now recommend. 34 | 35 | Vadim: we did research on LLMs in MDN. LLM.text is really just to make the content smaller. Currently they don't consume whole docs if they are too big. Context window might get bigger, this could be a temporary problem. No headers, footers, sidebars. 36 | 37 | Simeon: this seems like a model training problem, that providers should be souring accurate up to date data. Is this about trying to feed agentic systems supplementary data? 38 | 39 | Florian: when you ask an SO question there is a discussion where experts figure out the best solution. with LLMs the answer depends on you and what exactly you ask. 40 | 41 | Dom: LLMs are trained on a vast corpus which isn't optimised for web dev best practices. If we can provide a system where a coding agent can get access to best practices, then they get better outcomes. Training phase is not the right time because it is too much in the past, and it is entirely in the hands of whoever it training it. We can't influence that. Whereas systems like MCP servers we can provide input. 42 | 43 | Kadir: attaching docs to web feature IDs to scope them for an MCP server? Only need the docs that pertain to the thing you want to write. Web feature IDs as a way to scope that. There is a danger of LLMs using outdated patterns. 44 | 45 | Dom: say, if an LLM knows you're using a feature with an ID, it can get the right docs. But it can't tell the LLM about different web features that they don't know about yet. 46 | 47 | Kadir: but the MCP server can say, check with web features for relevant features, that refer to the thing you are trying to do. 48 | 49 | Vadim: like search engines. w3schools website tops search engines. What could we do? Nothing, because it's the search engine's internal algorithm, we can't influence it. But modern LLMs are still approachable, can partner with them and say, we provide good docs, let's work together. This isn't possible with search engines. 50 | 51 | François: LLMs move fast and it's hard to predict the future. But machines should be good at following links and understanding pointers to things, mapping from IDs to patterns that should be used. 52 | 53 | Mike (Bocoup): skeptical about changing practices for machines, should trust intuitions. But Dom's suggestion about context and moving people towards newer practices makes it more compelling. Helping people use older models to not always need the latest model represents some degree of harm reduction. 54 | 55 | Florian: a lot of people are using these things. These are people we used to talk to and we still want to be able to reach them. 56 | 57 | Estelle: we should not stop what we are doing because we also need to be feeding the AI good information. So not too much time working out how to work with LLMs but also to keep writing good documentation. 58 | 59 | Florian: but they are not going away. 60 | 61 | Lola: important that LLMs have accurate data, not nonsense. Not so much worried about people using LLMs in work, because of review. More concerned about non-engineers who want to build something for their business or side project, use LLMs and do not understand the code at all. These people are at higher risk of bad consequences (as are their users). Is this an ongoing thing? To Estelle's point, we don't want to be continually feeding the LLMs, how do we balance the work of writing tech docs? 62 | 63 | Florian: we are still writing technical documentation now. What you said related to context curation. Beginners have less context, more experienced people can ask better questions and get better results. How can we provide context to beginners? 64 | 65 | Vadim: speaking of hand-chiselled words: in this era of LLM content on the web it is important to keep everything human curated and have LLM policies for content. So we can give users guaranteed human curated content. 66 | 67 | Kadir: what goes into MDN still needs to be reviewed by humans. The source does not matter so much. 68 | 69 | Will: but this is a problem for reviewers swamped by poor quality PRs. 70 | 71 | Dom: IPR is also an issue for LLM generated PRs. 72 | 73 | Florian: the legal community is catching up on this and it will likely become more of an issue. 74 | 75 | Estelle: asking AI about new stuff, it is wrong because the stuff is new and there is nothing to read. 76 | 77 | Kadir: for code samples, though, if you review them. 78 | 79 | Dom: maybe for some trusted collaborators we might want to allow this but for too open-ended policies it is a lot of work for reviewers. Complete ban is excessive perhaps but controls are needed. 80 | 81 | Estelle: LLMs don't use best practices. 82 | 83 | Roy: first layer is documentation (W3C, MDN), second @@@, third is usage content (bots, agents), fourth is tooling (browsers, IDE). For documents, we can add metadata to improve them and how they relate one to another; 3rd layer, test with embeddings, prompts to guide LLM towards specs via vectors; 4th layer, maybe similar things could be done. 84 | 85 | Mike: I don't want to put my time into making people more stupid and lazy. If this is what we are doing then we are lost, including myself. Normal use case for LLMs is to generate code. People just want to get something done, not to read the explanation. Very transactional information need. Including myself in this, it leads to not making me think for myself, and I don't want to do things that facilitate this. Do we want other humans to feed people information the way machines do. Stack Overflow "help vampire", just keeps asking questions about the next tiny thing that they want to do, and LLMs are a supercharged version of this. Do we want to make that worse. Can we make it better? 86 | 87 | Florian: this is demoralising as a tech writer, you want to help someone learn something, understand a concept. 88 | 89 | Estelle: people are still going to school, maybe the teacher finds it and reads it. 90 | 91 | Dan: not if teacher use AI to grade homework and the students use it. 92 | 93 | Dom: in agreement with these challenges. Maybe instead of the LLM giving you code it gives you a challenge, and gives you feedback on it. There are ways to use them that make you smarter not stupider. but if they have access to the wrong data they may make you learn the wrong things. 94 | 95 | Mike: I don't want to do any extra work for that. LLM.text is the machine training us to do something for them. 96 | 97 | Dom: autocomplete makes you lazier too. But noone cares. Challenging to know where the boundary between this and it making you stupid is. 98 | 99 | Estelle: I learn from autocomplete because I can see what's available to me. 100 | 101 | Mike: some people don't like IDEs for similar reasons. So yes, not black and white. 102 | 103 | Lola: a study in the UK about AI use making us lazier has been debunked. So there isn't empirical evidence. 104 | 105 | Mike: it has personally made me lazier. 106 | 107 | Kadir: if the goal is to teach us things, I get it. But it's not about that, or even developers. It's just mediated through developers, the end goal is to provide users with an experience on the WP. There might be effects on other things. 108 | 109 | Mike (Bocoup): think of times we've found solutions by being inefficient and human. So long as we decide that there are some beneficial applications, it's worth considering how to make it work better. It's the end user deciding how they are using the technology, whatever our intentions are. 110 | 111 | Dom: you could ask, how much priority do we put in? I think there is a need here. Because if developers miss the best practices, we are failing our mission. But it is hard to know how much to prioritize it. It is a valid position to say, we don't have the resources to do this. 112 | 113 | Alan: maybe also a case of awareness, rather than devs using old docs, their LLM is using the newer docs. Much less energy efficient. 114 | 115 | Dom: yes, can we make it easy for agents to have access to the right information while being sustainable. 116 | 117 | Mike: there's already been an erosion of funding for documentation. Adding more stuff on top of it seems unsustainable for the team's resources. 118 | 119 | Florian: these systems are not giving back to content creators generally. 120 | 121 | Dom: yes, so it might be possible to get more funding for documentation in this way. 122 | 123 | Florian: description of problem space is useful even if we don't have answers yet. 124 | -------------------------------------------------------------------------------- /meetings/2025-06-03.md: -------------------------------------------------------------------------------- 1 | # W3C Docs CG call, 2025-06-03 2 | 3 | Present: Lola Odelola, Den McHenry, François Daoust, Patrick Brosset, Dipika Bhattacharya 4 | 5 | Chair: Lola 6 | 7 | Note taker: Patrick 8 | 9 | Joining info: 10 | 11 | To join the video meeting, click this link: https://meet.google.com/jdp-xvka-hyk 12 | Otherwise, to join by phone, dial +49 40 8081617306 and enter this PIN: 544 514 889# 13 | To view more phone numbers, click this link: https://tel.meet/jdp-xvka-hyk?hs=5 14 | 15 | ## Agenda 16 | 17 | 1. Welcoming more new folks 18 | 2. [Explore How Spec Explainers Are Used](https://github.com/w3c-cg/webdocs/issues/7) 19 | 3. [Outreach](https://github.com/w3c-cg/webdocs/issues/9) 20 | 4. [Web Doc Contribution Workshops](https://github.com/w3c-cg/webdocs/issues/8) 21 | 22 | ## Notes 23 | 24 | ### Intro 25 | 26 | Lola: round of intros would be good. This is Den's first time. More people usually, but there are various events, so we'll have a reduced group today. 27 | 28 | Lola: I'm Lola, one of the chairs of the group, with Florian (off), also W3C TAG, as invited expert (no corporate affiliation), lot's of standards. 29 | 30 | Francois: I work for W3c, part of the Team. Keep an eye on media and entertainement, and also developer experience, co-chairing WebDX with Patrick, focusing on web-features and Baseline. I also maintain tools related to spec edition, to improve spec quality. 31 | 32 | Patrick: at Microsoft, PM on Edge team, DevRel activities. 33 | 34 | Dipika: Technical writer on MDN team, I write a lot of docs, focusing on CSS a lot. As part of being on MDN, I do a lot of maintenance (issues, PRs, ...). 35 | 36 | Den: Front-end dev at Washington school of law. No experience in docs. I use the docs. 37 | 38 | Lola: very happy to you, we have something on the agenda relevant to you. We want to engage with more folks like you. 39 | 40 | ### Explore How Spec Explainers Are Used 41 | 42 | Lola: within W3C, standards are created by writing a spec, reviewed by the TAG. Part of that review process is that a spec explainer is written. Ideally the explainer would be written before the spec. This is where you flesh out the ideas. Spec explainers are very useful. But there's been a proposal to get rid of them. See https://github.com/w3c-cg/webdocs/issues/7 for the link. 43 | 44 | Lola: for those who do write docs, those who read specs, how do you use the spec explainer? Do you use it at all. Opening the floor for how people are using spec explainers. 45 | 46 | Patrick: use them a lot, much clearer than specs. Always a problem statement and solution that's written from the angle of a web dev (at least often). Makes my life a lot easier to write docs. 47 | 48 | Francois: Found them extremely useful, when they're written before the spec. I've organized a lot of workshops for W3C. Often ideas get raised, and people come to me asking how to push the idea forward. That's exactly when I say: look at the TAG guidelines and write an explainer. This works pretty well for that. I haven't used explainers after that. Once a spec is written, it's no longer a need that I see. Explainers are not maintained after that. But I wish specs themselves would go into that sort of details. Editors tend to remove as much prose as they can from specs, because that's harder to maintain. This is a bit of a pitty. 49 | 50 | Lola: With my TAG hat on, this is good to know. Most people seem to be in agreement that explainers are good to get ideas out, before specs are written. 51 | 52 | Dipika: Haven't looked at explainers so far. But I would really appreciate it if specs explained the problems being solved. Otherwise we often come up with really simple examples in docs. If I knew what big problem the spec was solving, that would really help make the right pitch for the feature in the docs. 53 | 54 | Lola: have you not worked with explainers because you didn't know they existed? 55 | 56 | Dipika: yes 57 | 58 | Lola: maybe a case for having a link to the explainer in the spec. Maybe would address Francois' comment too, where the prose doesn't have to live in the spec, but is at least linked from the spec. Explainers would still have to be maintained. Dipika, what you're asking for is in the explainers: considerations, problems, solutions, etc. 59 | 60 | Patrick: if the explainer isn't maintained over time, I don't care much, in my experience as a tech writter. I use the explainer very early in the process when writing docs about new features. 61 | 62 | Lola: I will post a summary of the discussion on the issue. 63 | 64 | ### Outreach 65 | 66 | Lola: we recently identified that we need to do outreach. I was wondering if we should talk about other ways in which we can integrate spec authors in the writing process. They know the tech that they created, they can write about it. But this could also be anybody who's willing to contribute to the docs. Maybe part of the spec explainer thing, we review the spec, and help the spec author compose those important sections like code examples. Or, should docs be part of the horizontal review process? 67 | 68 | Dipika: One thing that comes to mind, re whether writers should be part of the spec review process. We could contribute for naming features. Sometimes there are features that are not named similarly. They're not easy to use, if users have to renaming the name. So for naming features, we could provide feedback. Plugging in writers early on in the process could help. In my previous job, we used to review error messages, and user flow, etc. When we review features, we can do that level of review. Look at the code, and see, from the dev perspective, how this will land, and provide feedback. 69 | 70 | Francois: Your starting point is that it's hard to do outreach because it takes time. Turning that into the horizontal review process would take even more time. I would love to end up in a situation where groups would take responsibility. Same as how they take responsibility for tests. If they could take point on signaling that dev docs need to be written would be great. But hard to envision without taking more time. 71 | 72 | Lola: maybe collab between W3C and MDN. In a similar to how specs are written by people who write at browser vendor companies. Maybe there's something (note taker: missed the rest) 73 | 74 | Dipika: when we talk about outreach, what we were trying to do was outreach to devs, right? 75 | 76 | Lola: 2 branches, yes, dev outreach, we'll come to that next with the workshop. But also outreach with the standards process. An issue I found is that the specs can be quite complex to understand and parse. So plugging into that process earlier would help with this. 77 | 78 | Francois: An intermediary step could be a collab between WebDX and Docs CG. In web-features, in the explorer website, there's a link to MDN. That could be where we start detecting missing docs for features. BCD is extremely granular. But web-features could help identify areas where things are missing. Unless MDN already knows what's lacking. 79 | 80 | Patrick: yes, mapping JSON file on the explorer website which maps between features and docs on MDN. Incomplete mapping. Could be a way to find missing docs. 81 | 82 | Lola: So 2 things to think about. Missing docs, and bridge between spec writers and docs writers. 83 | 84 | Dipika: Yes, (note taker: missed this) 85 | 86 | Francois: on spec authors: it depends on working groups. Some have documentation in mind, some approach MDN directly. Some even provide the docs. And then there are groups where the spec authors are the implementers themselves, writing code and spec at the same time. More of a software engineer profile, who usually don't tend to naturally write docs (and less prose in general). 87 | 88 | Lola: in the scenario where the browser engineer is writing the spec+code. Do you think it would make sense to write docs also? 89 | 90 | Francois: would make sense, yes. But I don't know if they'd want to do this naturally and would have the right skills. Of course depends on the person, this is a generalization. But in a lot of cases, spec authors think the docs will be done eventually by someone else. 91 | 92 | Lola: Google has web.dev. For a lot of the things they implement, they also write on web.dev. They have code samples, and blogs, etc. There's something there we could utilize in that space. But it's mostly to champion their own things. 93 | 94 | Patrick: re Google, they have a lot of people in devrel, and likely a process where they do this systematically. 95 | 96 | Lola: if we had more writers involved, is this a process that could be feasible. 97 | 98 | Patrick: always a question of budget and priorities/investment. Browser companies document the things they work on primarily, through paying employees, contractors, organizations, because they want their features adopted. Are you talking about something more systematic, through this CG? 99 | 100 | Lola: just throwing ideas. What's a low barrier of entry? What's manageable? What can we do that is doable with the resources we have. 101 | 102 | Dipika: Comes down to what Patrick said. For example if I'm assigned to a feature, I will spend the time to understand it and document it, work with the spec authors and implementers. Wherever the writers are, they need investment from the company shipping the feature. 103 | 104 | Lola: next steps: unclear. 105 | 106 | ### Web Doc Contribution Workshops 107 | 108 | Lola: This is about the wider developer community. Not so much about spec authors, although they are part of it too. It would be benefitial of workshop for contributors to documentation, regardless of who you are. 109 | 110 | Dipika: what I said on the issue is specifically for folks like Den. We want developer feedback comoing back into the docs. We want feedback from real life usage of the feature. We're talking about involving writers early in the spec. We can also involve devs early into the spec process. This can translate into feedback where the feature, and the docs get better. 111 | 112 | Dipika: through that workshop, we can target all the stakeholders, especially the devs who are using the features, and get their view point on the issues they are finding about features, the hurdles they are facing. 113 | 114 | Lola: Den, would be good to know how you use documentation in your everyday work. 115 | 116 | Den: I've used MDN a lot over the years. I think a lot of people in my position, that's the primary source of information, from individuals. Like prominent people like Rachel Andrew, who are great communicator and have a platform. So for new features, that's through those folks. Otherwise for things that are more established, we go through MDN. 117 | 118 | Lola: in terms of contributing to MDN, have you thought about? 119 | 120 | Den: thought about it, always wanted to do, haven't done it. I've done frontend for a long time, still thinking I'm not a real developer/programmer. I'm really behind the scenes can of person. My boss has been encouraging me to do it more. But social anxiety. Putting yourself out there, and having your name, etc. I want to see what people are really doing and trying to get involve. 121 | 122 | Lola: to Dipika's poinbt, maybe a low hanging fruit is reporting real world examples that should be in docs, but aren't. You use the docs everyday, you use it in your work. I haven't written any production code in a long time. 123 | 124 | Dipika: If suppose, in the past, you've used MDN, if you thought you didn't understand something, or you had to go elswhere. Would it have helped if there was a Slack channel, and you could drop a message? To reduce the friction or the steps that devs find in contributing back to the docs, when using a feature. What would make it easier for developers to give feedback about how they use features. Wondering if it would be easier to provide more forums other than just creating an issue on the github repo. To request more examples, guides, etc. 125 | 126 | Den: Slack channel: I would worry this would become so unweildly for you. Wouldn't want to be on the other side. I think it should be a bit of a bother to report things. There's already stackoverflow. I used to monitor CSS on SO, to help people. Not a great way to spend my time. There's so many low quality questions and answers. This would be a better forum because there's a certain filter, where the people involved are more qualified. I'm saying there should be a certain amount of effort. I wouldn't be adverse to joining a channel, but I worry it would be deluted quickly. 127 | 128 | Lola: I don't think that's a major concern. I've seen it work well. For example for the webkit slack for their open source project. They have a code of conduct for how you ask questions, and prereq before asking a question. It doesn't mean that people don't ask questions, but it means that those questions that don't meet the bar are ignored. If you follow the instructions, you are not ignored. Somebody can easily say "please refer to the code of conduct". But yes, they have moderators, so something to consider. 129 | 130 | Dipika: MDN also has a Discord...so community helps out with some QA. 131 | 132 | Lola: next steps: we should put a draft together for the workshops we'd want to run. Identify 2 or 3. 133 | 134 | Francois: +1 to running workshops. Regardless of the project, what's hard is getting people to write their first PRs. It takes a lot of time to get someone to be fluent in the process, and the spec or docs. The mentoring process works, but scale is limited. So workshop can help multiply. 135 | --------------------------------------------------------------------------------