14:07:17 <RRSAgent> RRSAgent has joined #open-web-docs
14:07:17 <RRSAgent> logging to https://www.w3.org/2022/09/14-open-web-docs-irc
14:07:19 <Zakim> Zakim has joined #open-web-docs
14:12:04 <dom> Meeting: Documenting the Web platform: Open Web Docs and MDN  - TPAC 2022 breakout
14:12:06 <dom> Chair: Dominique_Hazael-Massieux, Will_Bamberg
14:12:08 <dom> Agenda:  https://www.w3.org/events/meetings/1651724a-9414-42f0-b787-08b3e93cc57c#agenda
14:12:10 <dom> RRSAgent, make log public
14:12:12 <dom> RRSAgent, this meeting spans midnight
14:17:52 <dom> RRSAgent, stay
14:17:54 <dom> Zakim, stay
14:17:54 <Zakim> I don't understand 'stay', dom
15:14:58 <dom> dom has joined #open-web-docs
16:12:47 <dom> agenda+ breakout
18:15:49 <dom> dom has joined #open-web-docs
18:25:24 <wbamberg> wbamberg has joined #open-web-docs
20:15:05 <dom> dom has joined #open-web-docs
20:30:10 <dom> dom has joined #open-web-docs
20:38:30 <wbamberg> wbamberg has joined #open-web-docs
21:07:02 <dom__> dom__ has joined #open-web-docs
21:40:59 <wbamberg> wbamberg has joined #open-web-docs
21:52:59 <dom> dom has joined #open-web-docs
21:54:34 <dom> Present+
21:54:42 <dom> Present+ AlexL, Gerald, Kadir
21:55:20 <dom> Present+ Joe
21:56:47 <Joe_M> Joe_M has joined #open-web-docs
22:00:10 <tidoust> tidoust has joined #open-web-docs
22:00:49 <dom> Present+ Will, Chase, FLorian, Estelle, Andy
22:01:29 <dom> Present+ LucasPardue
22:01:55 <dom> Will: this will be a session about Open Web Docs & MDN talking about how we document the Web Platform
22:02:04 <dom> Present+ ToshiakiKoike
22:02:28 <dom> Present+ PeterR
22:02:31 <lpardue_> lpardue_ has joined #open-web-docs
22:02:38 <kadirtopal> kadirtopal has joined #open-web-docs
22:02:44 <kadirtopal> present+
22:02:53 <dom> Slideset: https://wbamberg.github.io/tpac-owd-2022/
22:03:04 <laka__> laka__ has joined #open-web-docs
22:03:14 <dom> Will: OWD is an organizing employing technical writers to maintain and extend web platform documentation
22:03:18 <dom> scribe+
22:03:19 <laka> laka has joined #open-web-docs
22:03:37 <dom> ... we consider Web platform documentation is critical digital infrastructure
22:03:54 <dom> ... having access to good quality, systematically organized, maintained information is critical
22:04:08 <dom> ... having that done depends on tech writers and documentation engineers
22:04:31 <dom> ... quite often writers do more than writing - this includes information architecture, ensuring discoverability, maintenability
22:04:53 <dom> ... Open Web Docs exist through donations from corporate and individual sponsors
22:05:03 <dom> ... they enable us the work we do
22:05:15 <dom> ... sponsorships are managed via opencollective
22:05:36 <dom> ... That money hires people to work on Web documentations - these are the people working on OWD
22:05:47 <dom> ... most of our time is spent working on MDN
22:06:05 <dom> ... MDN is the top destination to learn about Web technologies
22:06:15 <toshiaki-koike> toshiaki-koike has joined #open-web-docs
22:06:41 <dom> ... maintained as open source, under CC-BY-SA, owned by Mozilla employing developers to maintain the platform and a team of writers
22:06:48 <dom> ... 2nd most cited site on stack overflow
22:07:11 <dom> ... MDN has about 11,000 pages, mostly JS, CSS, Web APIs, HTML, HTTP
22:07:16 <Kodajima> Kodajima has joined #open-web-docs
22:07:33 <dom> ... Web APIs are half of the number of pages, and one of the most unique value proposition of MDN
22:07:49 <dom> ... MDN used to be a wiki, in 2020 it went into github
22:08:02 <dom> ... maintained as a collection of github repositories
22:08:23 <dom> ... the main ones are yari (the site generator), MDN content is where the prose content lives as a massive set of markdown files
22:08:44 <dom> ... browser-compat-data maintains data about support of features in browsers
22:08:59 <dom> ... this also builds on repo maintained by W3C, w3c/Browser-specs and w3c/webref
22:09:04 <dom> Present+ Mike
22:09:23 <dom> ... mdn/content is a super busy repository, with 2600 contributors, 14K merged PRs
22:09:36 <dom> ... making MDN one of the most active repo on github
22:10:00 <dom> ... OWD works on MDN in two types of path: maintenance and project work
22:10:26 <dom> ... in terms of maintenance, a lot of is in PR reviews - 3214 reviews during the first semester of 2022
22:10:38 <dom> ... also fixing issues, triaging issues, interacting with the community
22:10:49 <prushforth> prushforth has joined #open-web-docs
22:11:01 <dom> ... we're still looking at improving our approach on this
22:11:17 <dom> ... we're able to keep the PR and issue queues under control, but it comes to a high cost
22:11:32 <dom> Kadir: re 17 reviews a day - that correlates to pull request
22:11:50 <dom> ... do most of them require a manual review? could they have been automatically reviewed in some way?
22:12:24 <dom> will: my sense is that most reviews trigger manual comments & suggestions, with various level of substantiveness
22:12:48 <dom> Joe: documentation maintenance doesn't lend itself well to maintenance
22:12:53 <dom> Present+ Berni
22:13:17 <dom> Will: we haven't looked at it properly
22:13:27 <dom> ... if we compare to azure-docs - they're busier
22:13:37 <dom> ... it would be interesting to hear from them
22:13:43 <dom> Present+ LucaG
22:14:03 <dom> WIll: even checking which reviews would have lended themselves to automation
22:14:09 <dom> Will: we also work on projects
22:14:30 <dom> ... OWD has a process for filing project proposals - anyone can fine one on our org repo, based on a template
22:14:47 <dom> ... which helps document the criteria they match
22:15:19 <dom> ... under the guidance of Steering Committee, which includes Apple, MS, Mozilla, GOogle, Coil, W3C, Igalia, Meta, JetBrains, Samsung Internet
22:15:32 <dom> ... the projects we work are a mix of writing new stuffs and infrastructure improvements
22:15:54 <dom> ... e.g. we converted our HTML source to markdown to improve the MDN authoring experience
22:16:07 <dom> ... the HTML was originating from the wiki and was really hard to maintain
22:16:45 <dom> ... this was done by building consensus among the MDN maintainers that led to solutions for the problems we identified along the way
22:17:18 <dom> ... Another project was the updates and expansion of WebXR documents, a big writing project
22:17:31 <dom> ... done closely with the Immersive Web WGs
22:17:38 <dom> ... sometimes impacting back the specification
22:18:08 <dom> ... We just finished a project around code sample modernization, to clean code that used no longer good practices
22:18:26 <dom> ... starting from the "Write the Docs" event, with a writing day as a way to involve the community
22:18:51 <dom> ... it started by fixing samples to no longer use "var", and grew into a project of fixing all JS
22:19:01 <dom> ... the work was mostly done by volunteers, under OWD guidance
22:19:21 <dom> ... also led to JS code guidelines that emerged out of a long consensus building
22:19:48 <dom> ... Another project we developed was complete documentation for ARIA role
22:19:55 <dom> ... working closely with accessibility experts
22:20:15 <dom> ... in all of these projects we collaborate with other orgs and experts
22:20:25 <dom> ... In our potential roadmap for Q4 or 2023:
22:20:40 <dom> ... a proposal to revamp the performance WG, with lots of details
22:20:54 <dom> ... revamping CSS color docs that needs refreshing given the recent work in this space
22:21:12 <dom> ... we'll also want to have prettier and eslint working on our code samples
22:21:25 <dom> ... we're running markdownlint already
22:21:46 <dom> ... this is made hard if you want to keep drive-by useful contributors
22:22:02 <dom> ... this needs to be approached carefully, but would have good results in our code sample quality
22:22:06 <dom> ... How can you help?
22:22:14 <dom> ... we're on @OpenWebDocs on twitter
22:22:18 <dom> ... you can submit projects
22:22:27 <dom> ... and get your employer to sponsor us
22:22:39 <dom> ... To propose a project, you file an issue following the suggested template
22:22:49 <dom> ... we like collaborating and look forward to working with W3C groups
22:23:09 <dom> ... we're in the process of choosing projects for Q4 - it's a good time (and always is) to submit projects
22:23:23 <dom> ... We're an open collective, all our financing we get comes from Sponsors
22:23:39 <dom> ... depending the level of sponsorship, this leads to different Member benefits
22:24:06 <Joe_M> q+
22:24:32 <dom> kadirtopal: beyond projects, is there a place where you list problems you're aware of that you'd like people to address?
22:25:15 <dom> ... a place of topics where volunteers could be mentored
22:25:47 <dom> will: quite a lot of projects we do involve substantive volunteer contributions
22:26:01 <dom> ... for instance, Estelle is driving work on fixing our alt attributes on images
22:26:07 <prushforth> q+
22:26:45 <lpardue_> +q
22:27:28 <dom> ack Joe
22:27:51 <dom> Joe: the figure of 6000 Web APIs pages was mentioned
22:28:05 <dom> ... in practice it should be even higher, around 8000
22:28:18 <dom> ... if you're working on particular APIs, help to document these APIs would be very welcomed
22:28:54 <dom> Alex: I'm part of a CG that is building a spec, and we're trying to figure out how to build our documentation so that it can be pushed to MDN down the line
22:29:13 <dom> ... a lot of the things that come from the MDN infrastructure, like BCD we have to shim ourselves
22:29:31 <dom> ... is there such a process? what maturity level would be expected?
22:30:04 <dom> Joe: it's not so much about the level of the spec, but about whether it ships
22:30:05 <laka> laka has joined #open-web-docs
22:30:54 <dom> ... specs can be moving target before it ships in stable browser
22:31:16 <dom> Alex: we're starting to look how it looks like in a browser, after having shimming it in a browser
22:31:49 <prushforth> * prushforth related to Alex's follow-up, our CG has been developing user docs for MapML https://maps4html.org/web-map-doc/
22:32:07 <dom> ... we want to make it MDN like
22:32:19 <dom> ... but had to shim a lot of the MDN infrastructure
22:32:27 <dom> ... e.G. BCD or spec links
22:32:44 <dom> Joe: I had to do something for some early doc on WebXR
22:34:01 <dom> q?
22:34:26 <laka> laka has joined #open-web-docs
22:35:26 <dom> ack prushforth
22:35:42 <laka> https://webmonetization-preview.netlify.app/docs/monetization-event
22:35:47 <dom> prushforth: same question as alex - we went through the same thing - we would like to use MDN to document our proposal
22:36:03 <dom> ... and facilitate donation of documentation down the line
22:36:15 <dom> ... we too use docusource using the same documentation model
22:37:01 <dom> will: one of the challenges that was brought up is rendering BCD
22:37:02 <prushforth> Link to our docusaurus docs https://maps4html.org/web-map-doc/
22:37:20 <dom> ... making BCD rendering more independent is something that has been looked at but not done yet
22:37:29 <dom> ... it's project that would need to be resourced
22:38:22 <dom> Alex: having a place to explain how to contribute packaged documentation, incl information architecture
22:38:32 <dom> ... we had to reverse engineer it from recent contributions
22:38:44 <kadirtopal> q+
22:39:05 <dom> ack lpardue_
22:39:15 <dom> lpardue: work at cloudflare, involved in IETF
22:39:44 <dom> ... thanks to MDN & OWD, make it much easier to introduce people e.g. to HTTP
22:40:02 <dom> ... new HTTP RFCs got published, possibly with sections
22:40:12 <dom> s/sections/new sections/
22:41:04 <dom> -> https://github.com/openwebdocs/project/issues/43 OWD project: Update HTTP docs (HTTP/2, HTTP/3, CSP, etc) #43
22:41:29 <dom> ... in general, how can we get expertise more involved in these efforts?
22:42:03 <dom> ... there may not be a lot of awareness that MDN is now maintained in github which would help with that community
22:43:07 <dom> q+ Mike
22:43:19 <dom> Dom: there is an OWD project for HTTP upgrade
22:43:33 <dom> Will: the project is well defined, not clear yet what priority to give it
22:43:45 <wbamberg> https://github.com/openwebdocs/project/issues/43
22:43:51 <dom> kadirtopal: re writing content to bring to MDN afterwards
22:44:16 <dom> ... can this be simplified? does docusource work well enough?
22:44:45 <dom> alex: the thing we have in common across our approaches are spec links and BCD
22:44:59 <dom> Peter: we don't maintain browser compat data at the moment, we only have a polyfill
22:45:38 <queengooborg> queengooborg has joined #open-web-docs
22:45:59 <dom> q?
22:46:08 <dom> ack kadirtopal
22:46:12 <dom> ack Mike
22:46:32 <dom> Mike: would be very happy to get Lucas' help in fixing HTTP docs
22:46:46 <fscholz> fscholz has joined #open-web-docs
22:47:13 <dom> ... I review a PR on HTTP caching article with a massive improvement
22:47:19 <dom> s/review/reviewed/
22:47:42 <dom> ... I'm not an HTTP expert, we ended up cc @mnot but he hadn't cycles for this
22:47:55 <dom> ... if you're interesting in helping with HTTP PR reviews, this would be super useful
22:48:13 <dom> Lucas: on a best effort basis, sure
22:48:25 <dom> ... HTTP is a wide field - e.g. caching is not my strength
22:49:31 <dom> Mike: re broken links, we updated the browser compat data to the new RFCs
22:49:45 <dom> ... there remain in-article references that probably remain outdated
22:50:10 <dom> ... the fact that a lot of ids were maintained in that update has been useful
22:50:36 <dom> q?
22:51:59 <dom> Mike: our open issue queue remains pretty small given how many we're getting
22:52:04 <dom> ... but that's still 600 https://github.com/mdn/content/issues/
22:52:14 <dom> ... which is intimidating or disincentivizing
22:52:57 <dom> ... we need more domain expertise to help with some of these issues
22:53:03 <dom> ... e.g. I can't help with WebGL issues
22:53:41 <dom> ... I'd welcome suggestions on how to identify potential contributors e;g. via stackoverflow
22:54:05 <dom> Peter: would it be possible to give StackOverflow reputation points for MDN contributions
22:54:12 <dom> Mike: good idea :)
22:54:28 <dom> Joe: the MDN PAB had discussions about gameification of contributions
22:54:54 <dom> Mike: that'd scare me, but SO credit sounds interesting
22:55:30 <dom> Joe: we could have a different repo for easy vs challenging issues
22:55:41 <dom> will: this can be done with labeling
22:56:01 <dom> https://dontcallmedom.github.io/mdn-issue-by-spec/
22:56:06 <laka> laka has joined #open-web-docs
22:56:51 <dom> RRSAgent, draft minutes
22:56:51 <RRSAgent> I have made the request to generate https://www.w3.org/2022/09/14-open-web-docs-minutes.html dom
22:57:07 <dom> Mike: a core contributor of MDN also contributes to docusource
22:57:46 <dom> will: in general, it'd be interesting to measure the difference between yari and an off-the-shelf SSG
22:58:01 <dom> Alex: it's a massive SSG, not very well documented or extensible
22:59:10 <dom> RRSAgent, draft minutes
22:59:10 <RRSAgent> I have made the request to generate https://www.w3.org/2022/09/14-open-web-docs-minutes.html dom
23:03:03 <lpardue_> FWIW: here's a quick one https://github.com/mdn/content/pull/20740
23:14:21 <laka> laka has joined #open-web-docs
23:22:25 <dom> dom has joined #open-web-docs
23:32:35 <laka> laka has joined #open-web-docs
23:37:28 <laka> laka has joined #open-web-docs
00:05:27 <laka> laka has joined #open-web-docs
00:37:10 <laka> laka has joined #open-web-docs
01:06:15 <laka> laka has joined #open-web-docs
01:09:00 <laka> laka has joined #open-web-docs
01:13:08 <laka_> laka_ has joined #open-web-docs
21:14:55 <dom> dom has joined #open-web-docs
21:58:01 <dom> RRSAgent, ye
21:58:01 <RRSAgent> I'm logging. I don't understand 'ye', dom.  Try /msg RRSAgent help
21:58:03 <dom> RRSAgent, bye
21:58:03 <RRSAgent> I see no action items