950811 - The 'Event Guide' needs a high level organization

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: General, defect, P3)

Description

[Adrian Custer]

User Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9; rv:28.0) Gecko/20100101 Firefox/28.0 (Beta/Release)
Build ID: 20131213004002

Steps to reproduce:

The dev.moz.org site contains something currently called the 'Event developer guide':
  https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Events
which seems (from the nesting of the page) to be part of the 'Web developer guide:'
  https://developer.mozilla.org/en-US/docs/Web/Guide
but both these landing pages are in transition and users lack a coherent overview of how this will all fit together.

All contributors to MDN need a shared, high-level overview (aka outline) of the structure of the "Web Developers' Guide" and its 'Event Guide' sub-component. This outline structures the writing of this more complex section to make it a coherent whole.

First, the relation between the 'Event Guide' and the "Web developers' Guide" needs to be made clear.

Second, the title of the 'Event Guide' should probably be shortened to that, or indeed the 'Event Guide' merely be a chapter in the 'Web ... guide'

Third, I have attempted to refactor the 'Event Guide' landing page with an overall structure. This starts with the 'overview' page I recently wrote, then uses the 'custom events' page which was written and finally turns to 'built-in' or 'browser defined' events. In the latter case, I attempted to develop some kind of systematic approach to the browser defined events:
  * device (i.e. hardware)
  * window (i.e. the rectangle on desktop screens, not the 'window' global Js object)
  * process (e.g. load)
  * user interaction events
      * 'click'
      * mouse
      * gestures
      * touch (modern and deprecated)
  * DOM modification (deprecated mutation events)
  * media events
  * network request events

This hierarchy is unsatisfying for 
  1) being incomplete,
  2) not being visible on the landing page,
  3) being developed without input from the wider community, and
  4) not being sure whether to organize the subject by topic, as here, or by emitter object.
The hierarchy needs to be fleshed out into a comprehensive outline of the topic of 'events' in the modern web browser. 

The MDN team needs to develop this higher level outline. This is properly the job of an Editor, that is someone who is overseeing the project to give it an overall coherence. There are also practical issues like the inability of outsiders to manipulate the pages which means the work will have to be done by the MDN team.

Once the higher level outline has been developed, then the individual topics become much easier to tackle.

Note that, as expressed in the overview summary page:
  https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Events/Overview_of_Events_and_Handlers
the 'event system' is generic and not at all tied to the 'API/DOM' as presented in the path of the 'Event Guide' page.

Comment 1

[BMO Automation]

MDN Web Docs' bug reporting has now moved to GitHub. From now on, please file content bugs at https://github.com/mdn/sprints/issues/ and platform bugs at https://github.com/mdn/kuma/issues/.