Sprints: O: Event reference docs refactoring

[Elchi3]

User story

As a MDN content writer or content lead, I want to have a detailed refactoring plan about the event reference docs, so I can fit work items into sprints in Q1 2019.

Acceptance criteria

User stories and tasks for the event docs refactoring are created, estimated and prioritized. (the checklist under "planning tasks" is done)

Planning tasks

• [x] Read Florian's event reference plan: https://docs.google.com/document/d/15F4ttUm7HSPKQNxKqzdiTHGTydDyFyVzyCVABbMHJKg/edit#heading=h.nr3wao5w0mzp and extract action items out of it.
• [x] Create user stories and tasks
• [x] Estimate work items
• [x] Prioritize work items and make them fit into sprints

[Elchi3]

The foundation tasks are written now. I had one API (WebSpeech) to play through a moving. In the MDN leads meetings today we decided that we should put 10 APIs into the next sprint, so I will create 10 issues in a similar fashion like I've done in https://github.com/mdn/sprints/issues/915

[Elchi3]

I have created 10 issues for ten groups of events to work on. They are linked above.
More pages to refactor can be found in the spreadsheet: https://docs.google.com/spreadsheets/d/1uxOmExdaQsSU0J-DWDu-D0J3idhYc20Z9-Oh4tql8-0/edit#gid=0

We have 262 web events and there are 135 events not yet in issues. So these 10 issues are half of the web event pages roughly. Of course there is more work besides moving web events (see foundational work above), so I'm not saying that we can get half of all the work done in one sprint, but I think this would be really great progress.

[ExE-Boss]

A lot of the events listed as “Legacy add‑ons” should be listed as “Chrome code”: https://github.com/mdn/sprints/issues/874#issuecomment-460825405

[Elchi3]

If you tell me which, then I can update #874.

[ExE-Boss]

I’m pretty sure it’s all of them.

[Elchi3]

Updated.

[wbamberg]

I've written up the procedure for moving and updating event reference pages, based on https://github.com/mdn/sprints/issues/915#issuecomment-460259746 and other stuff we have learned/decided since then.

This comment will be updated as we learn/decide new things :).

---

For each page:

• Find the target interface(s) for the event. This should be listed in the event's page. For example, https://developer.mozilla.org/en-US/docs/Web/Events/drag lists Document, Element as the targets.

• Move the page under the target interface, with the name "_eventname__event". For example: https://developer.mozilla.org/en-US/docs/Web/API/Document/drag_event. Update the page as described in "Event page updates" below, and update the main interface page as described in "Interface page updates" below.

• Check for translations of the event page (do this by hovering over the "Languages" item in the header). If the page has translations, move them as well (but don't bother updating the pages at all).

• If the original page listed multiple targets (e.g. https://developer.mozilla.org/en-US/docs/Web/Events/drag lists Document and Element as the targets), then you will need to do the above process multiple times, except that the second time, rather than move the event page, you will create a new page under the target interface and copy its contents from the page you moved and updated.

Event page updates

• Change the page title to _interfacename_: _eventname_ event. For example, "Document: drag event".

• Change the sidebar from {{EventRef}} to {{APIRef}}.

The page structure should be like:

• one sentence summary
• a blue box like the one here: https://developer.mozilla.org/en-US/docs/Web/API/IDBTransaction/abort_event. The blue box should not have an H2. The blue box should contain:
  
  
  
  • whether the event bubbles: Yes/No
  
  
  • whether the s cancellable bubbles: Yes/No
  
  
  • a link to the event's interface (this will often be https://developer.mozilla.org/en-US/docs/Web/API/Event but sometimes will be a derived event object that adds some extra properties.
  
  
  • a link to the corresponding on- event handler property, if there is one
  
  

The cells in the first column should be defined using <th>:

<table class="properties">
 <tbody>
  <tr>
   <th scope="row">Bubbles</th>
   <td>Yes</td>
  </tr>
  <tr>
   <th scope="row">Cancelable</th>
   <td>No</td>
  </tr>
  <tr>
   <th scope="row">Interface</th>
   <td>{{domxref("Event")}}</td>
  </tr>
  <tr>
   <th scope="row">Event handler property</th>
   <td><code><a href="/en-US/docs/Web/API/IDBRequest/onerror">onerror</a></code></td>
  </tr>
 </tbody>
</table>

• H2: Examples:

  • Make sure the page contains an example of listening to the event using addEventListener.
  • If the interface also supports the on- event handler property version of the event (it usually does), include an example of that as well.

• H2: Specifications:

  • this should look something like:

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
  </tr>
  <tr>
   <td>{{SpecName('SPECNAME', '#SPECFRAGMENT')}}</td>
   <td>{{Spec2('SPECNAME')}}</td>
  </tr>
 </tbody>
</table>

• H2: Browser compatibility:

  • This should use the {{Compat}} macro.

• H2: See also

  • Apart from any links it already contains, this should link to the on- event handler property (if there is one)
  • if this event has other targets (for example many events have "Document" and "Element" as targets), include a link to the other target(s). For example: https://developer.mozilla.org/en-US/docs/Web/API/Element/pointerup_event#See_also

• Some pages have different ways to format the info in the blue box. These should be updated to use the format in https://developer.mozilla.org/en-US/docs/Web/API/IDBTransaction/abort_event

• Some pages have a "Properties" section. This should be deleted (it duplicates the info in the event interface link).

• Some pages have a "Related events" section. This should be deleted.

Interface page updates

• Create a new H2 "Events" after the "Methods" H2. It should look something like: https://developer.mozilla.org/en-US/docs/Web/API/IDBTransaction#Events.

• For every event page you create, add a new list item: the <dt> is a link to the new event page, and the <dd> describes it. If the interface also has an on- event handler property, add some words like "Also available via the oneventname property."

• The interface page will typically have an "Event handlers" H3 under the "Properties" H2 (e.g. https://developer.mozilla.org/en-US/docs/Web/API/Document#Event_handlers). In that list, find the on- event handler property corresponding to the event you just added, and delete it. Ultimately we will retire this "Event handlers" H3, and only link to event pages from the "Events" H2

---

Some example migrated event pages:

https://developer.mozilla.org/en-US/docs/Web/API/IDBRequest/error_event
https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/audioend_event

Some example "Events" sections in the interface pages:

https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition#Events
https://developer.mozilla.org/en-US/docs/Web/API/IDBRequest#Events

[a2sheppy]

I would like for us to seriously consider naming the pages "_InterfaceName_: _eventname_ event" instead of simply "_InterfaceName_: _eventname_"

For example, I feel very much that "RTCPeerConnection: track event" is vastly more helpful, and much easier to quickly understand what you're seeing, than simply "RTCPeerConnection: track". Not to mention that we've been getting recommendations from the SEO side that we add things like this to titles anyway.

[chrisdavidmills]

I would support that.

[ExE-Boss]

Also, for the blue box (<table class="properties">), make sure that the first column uses <th scope="row"> and not <td>, otherwise formatting breaks on mobile.