[Bug 20128] New: clarify structure for API members that supplement core DOM interfaces

https://www.w3.org/Bugs/Public/show_bug.cgi?id=20128

            Bug ID: 20128
           Summary: clarify structure for API members that supplement core
                    DOM interfaces
    Classification: Unclassified
           Product: webplatform.org
           Version: unspecified
          Hardware: PC
                OS: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: info architecture
          Assignee: schepers@w3.org
          Reporter: letmespellitoutforyou@gmail.com
        QA Contact: public-webplatform-bugs@w3.org

Part architecture, part infrastructure. Bug relates to a topic in
11/18 site-content conf-call & earlier unresolved discussion in
"URL structure sanity check" public email thread.  Here's the
canonical URL structure for non-core APIs:

 /apis/<package>/<interface>/<member>

Good for new interfaces, but API packages often add members to core
interfaces (e.g. Document, Window, Navigator). Two examples:

* DeviceOrientation API adds a few events to the Window object. It
  does not add any new API interfaces.

* CSS Regions API (apis/css-regions) adds 'getNamedFlows' member to
  the Document interface. It's common to add such members simply to
  access specialized APIs.  (In this case, I placed it here:
  /dom/apis/document/getNamedFlows)

Question: should these members be added to /dom tree, or supplement
the existing /apis URL structure? E.g.:

 /apis/<package>/Document/<member>
 /apis/<package>/Window/<member>
 /apis/<package>/Navigator/<member>

Arguments in favor of the latter:

* Placing them directly on /dom interface page would otherwise list
  core members & more specialized members all jumbled together, and
  the distinction is info webdevs might find useful when viewing each
  /dom page.

* Maybe there's an opportunity to use templates to import
  supplementary members from /api to populate appropriate /dom
  interface. Page could be separated into core & non-core members.

* There's a benefit to being able to scan each /apis/<package> page
  and be able to view all relevant members from any interface,
  analogous to the everything-you-need-to-know structure of W3C specs.

* Relates to bug #20103: would like <package> pages to generate nested
  list allowing users to drill down directly to any member.

One caveat:

* What if users land on /apis/<package>/Document page? We're not going to
  re-doc it. Is a redirect to appropriate location under /dom possible?

-- 
You are receiving this mail because:
You are the QA Contact for the bug.

Received on Wednesday, 28 November 2012 18:59:55 UTC