Meeting minutes
<plh> present plh, fscholz
fscholz: the web platform consists of many interconnected bits maintained by different groups (TPAC slide from tidoust)
fscholz: presented at TPAC tools for understanding what is in the web platform and how to document it
fscholz: web platform is massive and growing (e.g. 15000 features in BCD)
fscholz: we are trying to help web developers to navigate the web platform in a more accessible way than the specifications (https://
fscholz: technical documentation is still the primary way developers learn how to code
fscholz: we're trying to understand what people don't understand (e.g. web security survey on MDN)
fscholz: how can the different groups coordinate better so we can have better docs that meet the needs of web developers: proposal is to make a Web Docs CG to coordinate
dom: quite supportive of the idea of bringing more coordination here. keyword is adoption: all of us are here because we think the tech is worth it, we want people to use it
dom: documentation is a key part of adoption, good if this group can bring a more systematic approach
dipika: likes the idea. This would need a buy-in from browser implementors and spec authors. We ened subject matter experts to review docs (e.g. spec authors) to make realistic examples
dipika: say what the feature is and where you need it, so devs can see the value in making use of it. Spec authors can help because they know why they have introduced it
dipika: tech writers are the bridge between spec authors and the world
fscholz: yes: we would like to invite chairs to talk about their specs. SWAG has been successful in getting input from spec authors
lola: would not want to make SME review a barrier to getting docs written
lola: TAG has explainer's explainer. This is a requirement to write a spec in as clear a language as possible, written by spec author and giving a high level overview.
lola: also have people going to other groups asking for information, meet spec authors where they are, rather than trying to get them to come into our space.
dom: +1 to meeting the spec authors where they are, and making us of explainers
dom: also code samples is a field where tech writers can benefit from spec authors
dom: big enabler for SWAG was the analysis that led to the creation of the group
dom: tech writers can give value by bringing analysis of the state of documentation
fscholz: with compute pressure API I was able to give detailed feedback on the spec, effectively adding QA to it, becuase these were some of the first non-spec-author eyes on the spec.
dom: so timing is important: typically explainer comes in before the spec, so it may be a good time for feedback.
vadim: one barrier between developers and specs is the language barrier. Supporting communities that support docs not in English could be a part of the remit of this group
fscholz: yes, in the charter we have listed many different docs sites, and it makes sense to take into account what others are doing, and try to get them to take part
wbamberg: re SWAG, it's been a place to get a lot of access to people with lots of knowledge and lots of interest in adoption
… based on a realization that adoption wasn't where it needed to be, which motivated people to get docs better based on the assessment that they weren't as good as they needed to be
… this created a valuable virtuous cycle in making it worth their time
… I hope we can reproduce something similar beyond SWAG
<estelle> WILL: SWAG. I felt lucky to be close to people close to the spec who care about adoption. Part was the study, but part was the realization that the guidance was too complicated or inconsistent. People came to the meeting with the goal of making docs better so we had people who wanted to work on this and it was worth their time. People are experts
<estelle> are busy. If they put it in docs, they don’t have to continue explaining. WHen people understand that, it’s beneficial. It might be overoptimistic to replicate that.
ddbeck: in the charter the list of sites is long and has varied audiences
ddbeck: maybe actual docs production is not in the scope of this
ddbeck: also consider bringing web developers in scope, so they can share their experiences
fscholz: yes, would like to get a better perspective on the experiences of developers trying to understand wp features
fscholz: it is a worry to put too much into this CG. We want to be focused and for this to be a place of practice.
fscholz: is the scope of work in the charter too long? If we could just have 2 or 3 things, what would they be?
dom: having a broad charter is not problematic: they key question is, how will you bring people in and keep them engaged
dom: what should be our priorities? maybe start with inviting SMEs to the group?
dom: won't expect many long-term participants, but maybe a core and people may come and go
dom: the key thing is trying it out, putting effort into getting people in and iterating
dipika: not everyone needs to be in the group all the time: people come and get help when they need it
lola: there used to be a web education cg, it closed down, do we know why? Can we learn anything from that?
dom: web education was a somewhat different focus, but worth talking to Chris, who was involved with this
wbamberg: +1 to dipika - a consulting model, a docs helpdesk model
… a prioritized todo list, a sense we're working on the right things would be a great outcome
… I don't think we need to expect people to stay for long
… e.g. a couple of years ago, we had this big focus on updating performance documentation; we did it, and then moved on
… similar to what is happening on security with SWAG
fscholz: with the perf docs we made a plan of what the docs should look like and worked on it with the spec authors. Now the basics are in place it is easier for everyone (including spec authors) to maintain them in the future.
dom: make sure we advertise the group to W3C working groups to know they have the resource available
dom: organizing something very visible at TPAC, like documentation helpdesk
dom: e.g. yesterday we had WebRTC meeting and discussed deprecating an API, and the corresponding docs updates.
dom: not only in MDN but in otehr doc sources on the web
dom: help WGs understand better about how to communicate spec changes (e.g. deprecations) to developers
dom: would be great if WGs knew there was a docs resource they could call on in situations like this
fscholz: Anssi from Intel: other horizontal aspects like security/privacy, performance
fscholz: encouraged by this conversation. Create a Slack channel to work on the CG submission.
dom: deadline for charter input?
fscholz: will consider, 2 weeks?
fscholz: will take action item to move CG proposal forward
<fscholz> Thanks everyone! How do I generate the minutes from here?