Attendees: Ali Spivak (Mozilla), Dominique Hazael-Massieux (W3C), Chris Mills (Mozilla), Kadir Topal (Mozilla), Daniel Appelquist (Samsung), Erika Doyle Navara (Microsoft), Patrick Kettner (Microsoft), Meggin Kearney (Google), Robert Nyman (Google).
Regrets: Rick Waldron (Boucoup)
- Date/Time: July 31-August 1, 2018
- Location: Microsoft Westlake office: 320 Westlake Ave N, Seattle, WA 98109, US
- 09:00: Arrive at the Microsoft office & check in
- 09:30: Breakfast, Welcome, & Orientation
- 10:00: 2018 so far - review w/ numbers [Kadir]
- 11:45: Lunch
- 13:30: Content roadmap review & prioritization for the rest of 2018 [Chris]
- 15:00: MDN Revenue deep dive [Ali]
- 16:35: Discuss board impact, suggestions for changes/improvements
- 9:30: Set up working sessions
- 10:00: The web platform strategy developers wish we had — introducing the PAB to our technology pipeline idea
- 10:45: Working Sessions
- 11:45: Lunch
- 13:30: Working sessions
- 15:30: Closing, agreements & commitments
- 16:00: "Meet the PAB" happy hour
Ideas that will be discussed if there is time.
- Business cases for technologies (pros and cons) on MDN (e.g. Service Workers, or "don’t use App Cache"). Guides to modernizing legacy code & how to move off. Want to do this, not sure if it needs in-person discussion (will start email thread [ACTION Ali])
- Talk to Google folks about how we can get their agreement on the license change to our data repo
MDN is a top-line KPI at mozilla, getting reviewed on a quarterly basis
MDN wins developer’s choice award for documentation and sample code.
Two growth strategies: reaching developers that are more action-oriented, and bringing MDN content into developer's workflow
Goals:
- Get more developers to visit MDN
- Get MDN into Developer’s workflow
Data:
- June 30th, 12.6M users, 47% yearly growth target.
- MDN content moved behind CDN (assets have been behind a CDN for a while) - improved page load time by 1 second
- MDN wiki platform only has 3 developers working on it (2 back end, 1 front end). Mostly doing maintenance and legacy fixes. Last year spent most of their time migrating MDN out of an old data center onto the cloud, this year most of their time was spent updating Django. Just about caught up with maintenance work; ready to start looking into new features.
Goal to reach about ⅔ of web developers by end of 2018:
- Estimated 11 million professional web devs around the world
- Estimated ½ of MDN traffic is currently web devs (front/back end, fullstack); other half is mixed (IT, admins, students,...)
MDN data migration into machine readable format, want to reach developers in their workflows. Working with VSCode, integrating CSS, more to come as we migrate more data.
It's difficult to measure MDN usage in external tools; need to figure out how to do this. NPM packages is currently the only way we are able to measure, which isn’t really useful.
As we get more data into more tools, there will be a mutual interest in quality content; need to work out what this looks like.
Provide developers with data on what’s being used. Discussion on good/bad herd mentality.
‘Should I use’ vs ‘can I use’
We should add reports for managerial people to MDN — data that shows how far something is from reality. 1-pagers for decision makers that explain business value of investing in certain technologies.
Would be useful to have/create a list of the most trafficked deprecated technologies.
Google's Lighthouse tool tells you what you are using that is deprecated, and suggests others (use this not that); doing an integration of MDN with this would be interesting. API linkage to MDN from lighthouse could be very interesting.
Added 2 new contract writers to MDN team, Irene Smith is focused on Firefox (and migration of Firefox) and Estelle Weyl is focussed generally on web technologies & APIs.
Performance: 90th percentile is at 4.7 seconds during the week, 6 seconds over the weekend
Weekend numbers explained, China/Asia don’t take weekends like western users do, and those markets experience much slower performance so it changes the numbers significantly on those days.
W3Schools has much better performance, especially on slow computers. Need to compete or be better; MDN usage in China and India growing and we need to serve these users better. Interactive examples important for performance, people want them.
For interactive examples, we use a combination of codemirror and proprietary code. Tim Kadlec will be helping us with suggestions and implementation. Interactive examples on MDN are currently in iframes, need to have a better solution for these.
SEO - most changes have been page by page, very inefficient. Focusing going forward on structured data where we can get more volume. We have guides for new content so best practices will be used.
MDN home page needs a lot of improvement, search is not good.
Firefox dev tools integration: last week we finished documenting CORS errors, will link to these from the Firefox DevTools. We currently link to JavaScript errors & that drives a lot of traffic. Would like to have a conversation with others (e.g. Chrome DevTools team) about integration.
Next set of error docs will be CSP errors.
- WebXR - Samsung team (Diego & Ada) can help with this, Diego could possibly help translate into Spanish. In Firefox roughly in release 71, in origin trials in Chrome.
- CSS Houdini - massive set of new CSS API documentation. Started as a loose, collective code name, now it’s become a "real" name for the set of features. The original thought was that it would just become part of CSS. Q: Do developers expect to see Houdini or are we reinforcing this thing we don’t want. Increases jargon and complexity. Pages on MDN should be the APIs themselves. Blog posts, etc. could talk about Houdini but the MDN docs should not. Makes sense to have a tag, landing page/guide, glossary page. More like a SEO keyword, etc. Do the glossary asap. Probably required some amount of bikeshedding to figure out what to actually call it as part of the documentation structure. Chris will own doing this.
- Rust > Web Assembly: apparently already in process of being documented by the Moz WebAssembly team, Chris is waiting to get this. Already have Emscripten documented on MDN.
- Web API interactive examples - trying to figure out how to do this on MDN & what makes the most sense as far as API usage goes. Starting with some DOM stuff, 2D canvas, and other very commonly used APIs. Would WebGL fall under Canvas? Yes, but it’s not as easy to write demos in Raw WebGL — mostly you'd just use a library, and we don't document libraries.
- MDN Performance docs need to be written and what little is there should be improved, Estelle will be working on this. Could be a great Hack on MDN topic to work on both the site and the docs (Toronto would be a great location for this).
- Web Audio - Ruth John will be helping document this (might also do Web MIDI if it gets prioritized).
- Web Payments API - Payment handler API needs to be documented; Chris following up with Moz engineers about this.
- Events documentation is a big mess - laundry list isn’t much use without the context. Need to decide what to do with these (came up when we got to these as part of BCD migration; have left them for now while we sort out what to do with them).
- Web Bluetooth; Samsung team interested in helping with this.
Other ideas that came up:
- Web USB - seems odd to ignore documenting this if we’re looking at Web Bluetooth
- Spatial Navigation (Daniel)
- Write documentation to make it easier to work across DevTools in browsers - generally if there is already good documentation for a tool we don't write it. Similar to the question of documenting frameworks on MDN, where we just don’t do it. Would drive more traffic, but with limited resources it just can’t be a priority. Whatever decision that is made needs to be deliberate because there will be questions. Need to be able to answer them with a well defined position.
- Stack Exchange data dump — Google is investigating using this data set to discover common questions developers are asking, and also to see if they are getting the right information to use the tools effectively. There may be a cross-browser goal here to help developers solve common problems regardless of the tools. Worth talking about common problems.
Continuing exploration of how to generate revenue from MDN - among other things, MDN currently funded by Firefox, while MDN is a browser-neutral project
Options:
- Corporate sponsorship / membership
- Membership (not donation): a program where members get something out of their payment - but difficult to determine what the quidproquo should be, and require up-front investment
- supporters program à la Guardian - to ensure continued growth of and improvements to the platform; maybe show list of donors à la GoFundMe
- Looked into job boards, but takes a lot of investment and is hard to make profitable - dropped that direction
- Advertising - but not satisfying and would probably not generate enough revenue - may do a round of testing to validate
ACTION: Ali to investigate using MDN membership program to create pool of developers willing and able to give direct feedback on spec design (especially having access to devs in different regions).
We are thinking about putting MDN on a separate domain, with developer.mozilla.org serving as a portal splitting off between Firefox stuff and MDN
How/did did we impact MDN? How can we have more impact? The conversations between board members and how that has led to joint projects between MDN and browsers.
- Board membership helps tie together different community engagements into a coherent whole.
- Awareness within standards community to integrate MDN into workflows, considerations
- Forum for finding opportunities for shared wins (e.g., VS Code integration), finding conflicts of interest (browser neutrality), input and validation from industry experts for prioritization of investments
KEY METRICS
Availability: percentage of web users running versions of browsers that contain the implementations of a web platform feature. We measure time-to-availability.
Q: Is this really only % of users? This would mean, in practice, that as long as a feature ships in the dominant browser it counts as being available. Realistically, many developers won’t use something unless it is in more than one browser because they feel that makes it less likely for the feature to be dropped later.
Adoption: how much a web platform feature is being used on the web. We measure the relative-rate-of-adoption.
At Microsoft, implementation decisions are made based on a combination of User Voice & interoperability. As far as which standards, it is probably similar to Mozilla.
There are areas where we know there is activity going on because there is agreement between different vendors, and that is why work is happening in that space (often with a direct product link). In other technical areas you only have 1 org pushing it & it tends to fizzle out.
There is a cost to making the wrong decisions.
Chrome Status tracker has helped Google make better decisions, shows what is in development and being proposed. One person built it, and it has had huge impact.
W3C has a framework to build and maintain roadmap of Web platform features on a given topic, e.g. the Media on the Web roadmap, including information about current and future implementations.
Q: Why are we using CSS Grid as an example? Why it is important that it was a coordinated release? Service workers - probably overcomplicated, could have better involved developers.
Companies like Facebook often want a feature available in 75% of market
- Microsoft data on API implementations
- Stats for usage in Chrome: HTML & JS, CSS
Service Workers, developer adoption still low, could we use MDN to help drive since something is not working.
Like the idea of the needs survey, but it is difficult to write the right questions, and need to be careful how we use the results. Concerns: might be shortsighted in terms of what is good for the web long term, as opposed to urgency to solve a problem "right now".
Survey would be the basis for the report but not the entirety of it.
Would it make sense for MDN to have User Voice like MS is using? It’s interesting, we’d need to build a program on MDN around it. [ACTION]
It's important to make sure it is representative of a broader input that just developers in Silicon Valley. How to represent a broader set of people and needs, including under represented groups and different geographies, different type of developers including those who don’t use the web? [ACTION] Kadir follow up with Samsung & Google, see if they can help reach a wider group, define targets?
The Samsung developer conference in November could help to get word out to non-web developers.
Step 1 is getting the requirements together.
Is there any empirical data we can pull together to help inform requirements?
Turn View Source into a joint vendor event, brand MDN View Source. Important to know how we’d brand it, timing, etc. Co-branding. Parity is important.
- A day of Wonky internals talks could be really fun
- Then 1-2 public days on web technologies
- Pavilions for either companies or specific technologies
- Getting input from developers as opposed to just talking at them would add unique value to the event. Let people "vent" about what is difficult about the web.
[Action] Ali to send email asking for committee members input, and schedule a follow-up meeting.
Last year we had a breakout session on MDN, this year the suggestion is for us to organize another breakout to report on what happened in the last year. Ali, Dom, & Dan will be there.
Monday night dev meetup, Ali presenting on MDN
Will be asked questions about EPUB# at this session; need an answer (see below discussion).
EPUBS3, IMSC (captioning), feel they would benefit from being documented on MDN, even though they are not implemented in (all/many/most) browsers. Would it make sense to create a “peripheral technologies” section on MDN.
We will write up a set of rules for additional technology documentation
- Separate architecture on MDN from core web docs, is useful/interesting for web developers
- Has a community willing to document and maintain the documentation. Agree to
- Is not documented elsewhere
[ACTION: Chris to write up the rules of engagement for peripheral technologies and information architecture to host them]
It would be cool to have the ability to invite discussion/have early feedback mechanisms included in documentation page. Also have a tag for it? Call out that feedback is important.
Need to build process around this,
Maybe have surveys people could answer?
[ACTION] Chris can try testing this & build macro, think about process and timing for maintaining this content/links [action] Dom will reach out to find spec groups who are willing to be testers and welcome “outsiders”. Then give a link to Chris.
How do we keep the MDN community open and welcoming to everyone (especially as we add new members/grow users)? What problems actually are there on MDN?
Our demographics are not great — users tend to be largely white and male, just like most other spaces.
Great hidden mass of diverse developers, who are using MDN or could be, but they feel it is not for them.
Are there ways to make the site feel more comfortable for diverse groups? Either by design, by language, by the way we talk about the community?
Even though the Wiki is fairly easy to use, you need to have a certain comfort in your own skills and confidence to use the edit button and make contributions.
Getting in touch with the MDN team is daunting, or more daunting than it should be.
Part of it is that the writing team was traditionally male, but this could change now we have two female tech writers. Our M/F ratio on the team is now 50/50.
Community management is challenging.
Let's look at ways to invite more people in to contribute, particularly those from diverse groups.
Contributions are largely casual, or drive-by. People don’t really stick around.
Having a conversation with others is more difficult than it should be.
A lot of contributions turn into turf battles. Places like Wikipedia have seen contributions decline because of this.
Actions going forward:
- Let's turn this into a board side project.
- As more content is moved to GitHub, let’s look at how we can build in community involvement tools, pathways, etc.
- A working group to look at this, both branding and representation, and specific design issues.
- And attracting contribution community
- Create sketch/brainstorm by TPAC
Dan’s team could provide some resources to look into this problem, Meggin really wants to help.
The homepage could really do with some work. People want unicorns, fun stuff, not corporate 2-color stuff.
Look at Glitch as an example — great at blogging, and their brand is all about inclusion. Glitch has people’s faces on it.
As part of the Mozilla survey suggested in another part, we should specifically target universities, code schools, etc. Show specifically how this vertical differs from the MDN audience at large.
Over the last 18 months, we moved (some) CSS data and Compatibility data to MDN. This has been really successful — for example in the browser-compat-data repo we’re struggling to keep up with community PR’s.
However, it’s all been data, not freeform text.
Main issues here:
- Localization of the content we store
- Macros in text; how would they work in a GitHub repo?
- What format would we store the content into?
So questions:
- How have others solved localization?
- Are there any cautionary tales to share with us?
Localization is really complex — Google tried to community drive it for some time, and it worked well for some locales, but eventually they hired a localization firm to handle the initial localization, and regular (say once a year) updates.
Localization tooling? A few years ago, they built the Google web developer site with app engine, and published it via GitHub. But then it became complex to get that included inside the main Google site repository when an architectural change was decided on.
They ended up with a script that finds out what changed, creates bugs and new content, and then pushes the new content to another repo. If all content can live in GitHub, then you are OK.
For Windows docs it was really hard as some stuff could be public, and some stuff was not for public consumption so had to be kept in a private repo.
Storing MDN content on GitHub is complex, as MDN is one consumer of the content, but it also needs to be made available in other contexts.
The PR model is obvious and comfortable for web developers, but localization is a different skillset. Do we expect localizers to use the same toolset?
Also, we need to manually check and merge each PR. How do we deal with PRs in languages we don’t understand?
We could use Pontoon, but then the localized versions would then live inside that, rather than inside the same repo as the English versions. This could become its own community, separate from the English content.
Google launched the Chinese version of Google Developers, but not much localization of it has happened.
Localizations get outdated very quickly. After a while it makes more sense to re-translate the English from scratch, rather than trying to work out what changed. Google support has a team that handles translations.
Need to work out technical details of the l10n.
Action: Erika to follow up with l10n decision makers to see if they could offer some resources to get the short description localization done, e.g. on behalf of Code.
Interactive examples tested/linted. Good, because these are the most examples on the page. But there are also other examples that need attention too.
Possible learning session for future — get us talking to some localization experts. Various members of the group could find people to talk to.[Action] Ali will follow up with Meggin and Erika to figure these out.
- We want VSCode to use data from MDN, but also link back to MDN.
- We don’t know if Code would be interested in this, best next step is to talk to Pine
- And give him the short description plan to look over.
- Also want to start look at JS integration, which would be a different owner — find this owner. (Maybe Chakra/TypeScript teams?)
- We have lighthouse best practices (e.g. don’t use document.write()), but the MDN docs don’t reflect these. We’d want to make sure the messaging aligns, or at least check why not, if not.
- Idea - add into lighthouse info on the deprecated features as specified in MDN BCD
- Lighthouse team might want to have links from MDN back to lighthouse, or other things — e.g. what is the value proposition for lighthouse? Chrome DevTools team are very product-focused.
- How to measure MDN data/info usage in external tools
- First need to define what data we need.
- Write document on why we should collect with this data, how it is beneficial to users, how we will use it, how often is it collected (e.g. every mouse over, or what?)
- Would we need an API server, to collect data on run, on open, etc.?
- Convenience methods, ideally server side, make it as easy as possible to
- Endpoint that is capable to deal with spam
- Best practice for devs, why we are doing it.
- Under what circumstances do we want to have data collected
- Bower as an example for one tool that did it
- Ran out of time for this one.
- Would need to look into this.
- Talk to the DevTools folks about integration.
- Start with creating an extension in the same way that we did with the Firefox extension; Eduardo Boucas could create a Chrome version of his extension as a first look.
- Also talk to Chrome folks like Alex Russell, Pavel, etc.
- Integration opportunities with more external dev tools (specifically error messages, but may be more opportunities like short descriptions)
- For Firefox DevTools, we are planning on linking to CORS errors and CSP errors from the errors as they appear in the JS console.
- Could we also get other browser vendors to link to our error message pages?
- Let’s ask Kayce where or if error messages are currently documented. Could we do this on MDN instead, or at least include the Chrome versions of error messages too? We do this on some pages already. For example see the Invalid_array_length reference page
- We are also putting CSS property descriptions into Firefox DevTools at some point.
- For integration with Edge DevTools, i18n would be a hard requirement before we can go anywhere.
(We ran out time to discuss this, but this is a problem we need to solve ASAP on MDN.)
Used to be just documented on the same page as the constructor (or whatever) they are used in, but more recently they have started being used across more than one feature.
So we are going to start explicitly documenting them on their own page trees, in the same way as interfaces.
Example: https://developer.mozilla.org/en-US/docs/Web/API/EffectTiming
Also need to list dictionaries and types/enums separately in API sidebars
Interfaces with Inheritance
Docs are confusing to developers
Example: https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot
Inherited by
https://developer.mozilla.org/en-US/docs/Web/API/Document https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot
Then we include links to the DocumentOrShadowRoot members on each of the above pages.
But no developer is going to search for say
DocumentOrShadowRoot.activeElement
They will search for
- activeElement
- Document.activeElement
- ShadowRoot.activeElement
See Sheppy's idea
have a macro along the lines of {{pageinheritance}} (special version of {{page}}) that takes content from the inherited page and puts it into the inheriting page, e.g.
DocumentOrShadowRoot.activeElement -> Document.activeElement
But then finds all special code/pre/a etc. elements that include the inherited interface name and replace them with the inheriting interface.
So pages would need to be created multiple times, but not the content for those pages.
Other example: BaseAudioContext -> OfflineAudioContext/AudioContext
Mixin pages would be dealt with in a similar way to inherited interfaces.
Sheppy also thought we could include a macro to insert information in the page about where a feature is defined: https://discourse.mozilla.org/t/mixin-presentation-idea/26189
October meeting? Coincide this with TPAC?
January meeting? January is good, just like with the previous one. Let’s pencil in the week of the 14th Jan 2019. Ali to send an email to figure out location & host
Also can we have more regular calls? It would perhaps help us to focus on keeping things moving, keeping things current, stopping them from becoming deprioritised. Should we have a regular monthly call? Or just a regular monthly update?
Regular six-weekly call Regular email update before call, plus more discussion around revenue, etc.
- [ACTION: Ali] Add a session on Wednesday to look into putting together a coalition of folks from across Google and Microsoft to work on MDN performance.
- [ACTION: Chris] Work on plan for Houdini documentation — what to call it, how to structure it, etc.
- [ACTION: Ali] Suggest Toronto as location and Performance as topic for our 1st 2019 Hack on MDN.
- [ACTION: Ali] Investigate using MDN membership program to create pool of developers willing and able to give direct feedback on spec design (esp having access to devs in different regions).
- [ACTION: Ali] Produce an annual report of the PAB achievements with input from PAB members
- [ACTION: Kadir?] Look into how we could use UserVoice at MDN in a program
- [ACTION: Kadir] Follow up with Samsung & Google, see if they can help reach a wider group, define targets
- [ACTION: Ali] Send email asking for committee members input, and schedule a follow-up meeting.
- [ACTION: Chris] Write up the rules of engagement for peripheral technologies and information architecture to host them]
- [ACTION: Dom] Reach out to find spec groups who are willing to be testers and welcome “outsiders”. Then give a link to Chris.
- [ACTION: Chris] Try testing this & build macro, think about process and timing for maintaining such content/links
- [ACTION: Erika] Follow up with l10n decision makers to see if they could offer some resources to get the short description localization done, e.g. on behalf of Code.
- [ACTION: Ali] Follow up with Meggin and Erika to find localization experts to talk to, to help work out GitHub content localization (related to getting MDN content on GitHub)
- [ACTION: Ali] Write an email to reiterate ideas on MDN D&I and start off the process of making MDN more inclusive and welcoming of a diverse user base. Meggin wants to help, Daniel might also have resources.
- [ACTION: Kadir] Start off this process of looking into how we could get JS docs integration in VSCode (different owner, maybe Chakra/TypeScript teams? Ask Patrick/Erika for help.)
- [ACTION: Meggin] Give Chris link to link of best practices included in Lighthouse.
- [ACTION: Chris] Take list of Lighthouse best practices and see if we cover all of them on MDN. Work out plan for covering the ones we don't cover.
- [ACTION: Kadir] Write document on how/why we should collect usage data of MDN docs/data in external tools...how it is beneficial to users, how we will use it, how often is it collected (e.g. every mouse over, or what?)
- [ACTION: Robert] Talk to Chrome folks like Pavel/Alex Russell about the possibility of including browser compat data in Chrome DevTools.
- [ACTION: Meggin] Talk to Kayce about where or if Chrome error messages are currently documented. Could we do this on MDN instead, or at least include the Chrome versions of error messages too?
- [ACTION: Ali] Send out e-mail to figure out location/host for next PAB F2F.
- [ACTION: Ali] Set up Regular six-weekly call, plus regular email update before call, plus more discussion around revenue, etc.