Attendees: Chris Mills (Mozilla, Chair), Daniel Appelquist (Samsung), Reeza Ali (Microsoft), Kyle Pflug (Microsoft), Joe Medley (Google), Dominique Hazael-Massieux (W3C), Kadir Topal (Mozilla), Ali Spivak (Independent).
- Date/Time: June 18th 2020, 09.30 Pacific / 17.30 UK time / 18:30 Europe
- Location: Mozilla Zoom room
- Meeting kick off
- DNA survey update
- Virtual W3C TPAC and involving dev community in virtual breakout sessions
- Are WICG specs standards track? (Related to BCD issue #6103.)
- Adding webhint to the Understanding client-side tools overview topic.
- MDN and plain language checks/guidelines
- E.g. how could we test this?
- What English constructs trip up non-native speakers the most?
Recently there has been a lot of work done on contract agreements, but by the end of this week we will have funding secured.
The next task is to talk to Pinpoint, the agency we are using to manage the surveys/reporting
Timeline:
- Kickoff by mid to end of July.
- Report in Q4 (deadline Nov 30th)
The Virtual TPAC (see next item) is at the end of October. Could we share some findings there?
Immediate next steps are to get stakeholders together to agree on survey structure, make sure everyone agrees with the form. Answer the big questions.
We will aim to move quicker this time — shorter period for feedback, less immediate stakeholders this time (30 last time, let the expanded group provide feedback later on.)
Related - we are looking for a contractor to do user research/project management and own the project on our end. Let us know if you know suitable people!
Is there a Job posting to point to?
ACTION: Kadir to create job posting.
DNA followup w/Robert/Phillip - slides linked above Survey was run on MDN, plus interviews with 13 people, all about compat data. Draft report also linked above. Feedback welcome on this. ACTION ALL: Provide feedback on report.
This year the W3C are hosting a virtual TPAC, comprised largely of breakout sessions Scheduled for October 26-30, 2pm UTC start on each day, it is likely to be free. Still figuring out details, but all week. Identify topics ahead of time.
They will open relevant sessions up to any interested web developers, but some will be closed.
Dom wants help with outreach, when the time comes, and also help with some sessions. Good topics - intersection of MDN and standards. BCD, DNA, etc. Education sessions? Maybe? Breakout sessions need a certain amount of marketing
Joe — free could mean a lot more attendees. Dom — Registration will create a cap.
This is partly due to inconsistent experimental status banners on pages; we need to fix those. Sometimes things look scarier than they should be (e.g. if tech is implemented in multiple browsers, not experimental?)
And experimental status on BCD needs work — this is binary, but reality it is a lot more nuanced What does “on a standards track” mean? If it has a reasonable trajectory, then it can be considered to be on a standards track, even WICG work.
Good examples when binary doesn’t fit — Web Bluetooth. It is not really experimental, even if it is only one engine. Still very interesting to a certain group of developers (also WebUSB, WebSerial) Big experimental warning sign not really appropriate Kyle suggestion - “Stable, but not widely-supported”?
Dan — TAG looks at where proposed new standards are being developed. What is the trajectory? Where is it headed after WICG? Standardized? Actively developed? Stagnated? This ties in to how it should be represented in MDN.
TAG tries to be as consistent as possible. MDN is aiming to do away with status, and more look at implementation, where it is specified, trajectory. Spec data in BCD?
ACTION: Chris/Kadir talk to Dan about what TAG is doing. Also talk to Joe about status data in MDN? And talk to Florian about what our approach could be on this, from the MDN side.
+1 from MS side (Stephanie Drescher & Sean Larkin would be the MS folks to talk to here), and W3C.
Reeza would love to add webhint information to the tooling documentation. There a number of other common tools (AXE, Snyk, etc.) which webhint integrates - as we look at bringing in webhint, it might be worth considering whether some of those other tools as well.
ACTION: Reeza/Chris talk about webhint addition.
Joe - did research into this, but would love to do more.
Readability formulas - mathematical judgement of whether text is readable. They don’t seem to do so well with technical documentation. They make presumptions about things, e.g. shorter words are better.
They are often designed by some linguistics professor, without field testing.
Even a good automated test would have to be recalibrated every 10 years or so, due to changes in language.
Hemingway test? Hemingway’s aesthetic was plain simple language, but his own writing doesn’t pass the test named after him.
Dan - can be down to cultural communication issues. Part of the issue - we are all really experienced web folk, so we come to articles in a very different context to beginners, especially those in different cultures, marginalised groups, etc.
Ali - this is not an uncommon issue. At new company - running into the same issues Difficult when you are new to tech, and taking in a lot of new information.
Reeza - Tools like Fleisch Kincaid are good to run on new documents, to get a general idea. Give you grade (6 or above recommended) For tech docs, grade 9 recommended.
Standard technical English - aviation guide, but still a lot of good learnings.
Writing for non-native english speakers — Microsoft have some observations to share E.g. stay away from words with dual meaning — e.g. “can”
Kyle — there needs to be an angle of clarity in technical writing Readability is often measurable by an algorithm, but we also need an understanding of process, and what do beginners not know.
Joe - we should compile a list of things we try to do as tech writers to avoid readability problems. For example hierarchy of prerequisites (Called didactics by educators, at least in the U.S.)
Is there anything we can test algorithmically? In terms of writing articles, we should pick out terms that will cause problems and find a way to exclude them from an algorithmic test — we should be explaining these. Everything else in terms of the content should be intuitive.
Dan suggested testing with real people from different locales. Focus groups, to find out what the biggest issues are in terms of an international understanding of technical English. This would be a lot of manual work, we’d need to pay people, but it would be very interesting to research this.
ACTION: Chris to start resource on this, see where we can get, see what’s already available
- Chris to create doodle poll for next meeting - DONE
- Kadir to create job posting for the DNA UX/PM role - BEING DONE INTERNALLY AT MDN; KADIR TO SHARE WHEN AVAILABLE
- Everyone to provide feedback on the BCD report Kadir shared (Issue 78)
- Chris/Kadir to talk to Dan about what TAG is doing WRT spec standardization status. Also talk to Joe about status data in MDN? And talk to Florian about what our approach could be on representing specs on MDN — we've talked to Florian, and we've agreed that he will investigate this next quarter. So there is no immediate action here. Florian or myself will be in touch with you all soon enough.
- Reeza to talk to Chris about webhint addition on MDN — DONE.
- Chris to start planning how we could get feedback on improving MDN international legibility, start a resource on dos and don’ts of tech writing, and see what’s already available (Issue 79).
Video call — July