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