Brainstorm how we can better integrate MDN with other GH-based functions such as spec process

[chrisdavidmills]

Now that MDN is on GitHub, there is an opportunity to integrate it with other GitHub-based functionality, such as standards specs.

It would be good to brainstorm exactly how.

[dontcallmedom]

paging also @sideshowbarker who would be good to involve on this

[chrisdavidmills]

From PAB meeting notes that @robnyman wrote:

Adrian had a proposal about MDN and explainers. From OWD Roadmap:

• Make MDN the home of new platform proposals (aka “explainers”)?
• When a new proposal is made at WICG it should be spec’d using a template defined by MDN which means the feature is already documented if it gets adopted and implemented.
• The process could be:
  • Write up a proposal and submit to a “proposals” section of MDN
  • Make a post in WICG forums to request feedback
  • Migrate from proposals to documentation if adopted

[dontcallmedom]

I like the overall direction, although having the explainers hosted directly in MDN may create too much practical friction - in general, having the explainer hosted in the same place as the spec helps in the early phase of iterations on the idea, helps having a single place to track related issues, helps with IPR considerations, etc.

I think the low hanging fruit is on the template bits - right now, spec writers are encouraged to write explainers following a template maintained by the TAG (maintained on github) - I can't imagine any resistance to improving that template to make the explainers a better match for MDN migration.

[dontcallmedom]

for the explainer stuff, we had previous discussion on this in #23 and #65 - with #65 still open, this might be the better place to follow up on that particular aspect.

What I mind in terms of MDN/Spec workflow integration here was more about figuring out a process whereby we encourage spec authors to flag pull requests that should induce a change in the relevant MDN documentation, and keep track of that need one way or another.

Sketching what this could look like:

• for every GH repo corresponding to a spec documented on MDN (which I feel reasonably we can compute), we install a GH bot of some sort that ask pull request submitter to assess whether the change induces documentation change (that bot can use heuristics so that it asks as little as possible - e.g. only react to the spec files themselves)
• when PRs get merged that have that flag set, this gets added to a pipeline of updates for MDN (possibly simply raising an issue in mdn/content, with some labeling)

[dontcallmedom]

we also had similar discussions in #26 where maybe we should consolidate this discussion

[chrisdavidmills]

We also had a long and interesting discussion about this in a recent MDN editorial meeting.

The potential action items from that were:

• ask spec authors what they'd like to see in specs in terms of dev content
• or ask what they usually put in the specs
• Try to get agreement on a template of items that could be added to mdn and the spec
• Try it out on a couple of specs
• Mike - if something is not clear on MDN, and you find that it is not clear on the spec, file a PR on the spec as well.

[chrisdavidmills]

I had an interesting meeting with @jpmedley and @robnyman about this too. Our conclusion was that it is going to be pretty difficult to reliably have a consistent MDN writer involvement with spec explainers, as our work tends to be actioned by feature implemention in browsers, not spec status. If we got involved too early, then the explainer work would not be that useful to us, as it would probably be out of date by the time we come to put parts of it on MDN. We also don't want this to turn into another work item that we are expected to have responsibility for — we just wouldn't have the time.

Instead, we felt that a simpler, lower-maintenance interacgtion might be good, along the lines of:

1. Provide a rewrite of the TAG explainer template, as @dontcallmedom mentioned earlier. @jpmedley already created a proposal for this, and I agree strongly with the structure of it — the idea being that the structure is brought much close to parts of MDN docs structure, so that when the docs are written, bits of the explainer can just be lifted off and used on MDN. If there is any trouble getting this rewrite approved, @torgo could probably help there, and provide further feedback.
2. Leave explainer writing and responsibility in the hands of the spec writers, but extend an open invitation to them, that MDN writers are happy to help or produce feedback if desired.

If this seems agreeable, then I'd like to suggest that @jpmedley collect feedback on his explainer rewrite, and then update it. Once we are agreed, he could then create a PR to update the TAG template.

[jpmedley]

Here's the proposal