2012-11-08

‎No differentiation between objects and listings:

← Older revision

Revision as of 04:55, 8 November 2012

(3 intermediate revisions by one user not shown)

Line 1:

Line 1:

This article offers a methodology for adding new API documentation pages to Web Platform Docs. It provides a process for adding several new pages -  as a branch - to the wiki. The discussion cites as an example the creation of  the [[apis/webrtc|WebRTC API]] pages.

This article offers a methodology for adding new API documentation pages to Web Platform Docs. It provides a process for adding several new pages -  as a branch - to the wiki. The discussion cites as an example the creation of  the [[apis/webrtc|WebRTC API]] pages.





The purpose of this article is to provide for the creation of new API pages. It advocates taking a different direction from the way the current API pages are laid out, and it cites those pages as examples not to follow. Implied with this methodology is the eventual reorganization of and improvements to the existing API pages - and that should be done - but the immediate purpose is to provide the community with a new, better way to create API pages.

{{TODO|Once the final methodology is in place, and the fixes cited by the TODOs are in, remove all the TODOs like this one.}}

{{TODO|Once the final methodology is in place, and the fixes cited by the TODOs are in, remove all the TODOs like this one.}}

Line 11:

Line 9:

{{TODO|This "Problem" section will be removed from the final, user-facing page.}}

{{TODO|This "Problem" section will be removed from the final, user-facing page.}}



The way our '''apis''' namespace is drawn out
is inadequate to
accomplishing the goals we had for the URL architecture. We wanted URLs that delineated the hierarchies inherent with the coding artifacts in the documentation, for the purposes of storing the content in a predictable, logical fashion, and providing the user with equally predictable, logical navigation.

+

The way our '''apis''' namespace is drawn out
leaves us short of
accomplishing the goals we had for the URL architecture. We wanted URLs that delineated the hierarchies inherent with the coding artifacts in the documentation, for the purposes of storing the content in a predictable, logical fashion, and providing the user with equally predictable, logical navigation.

The scheme in place currently, however, omits some key elements needed to achieve those objectives, and results in ambiguous or conflicting delineations.

The scheme in place currently, however, omits some key elements needed to achieve those objectives, and results in ambiguous or conflicting delineations.

Line 19:

Line 17:

==No differentiation between objects and listings==

==No differentiation between objects and listings==



Our WPD:New_Page page provides for the creation of API Listing pages
where
the API
is described. The purpose of these pages is to
list all of the API objects in
the API, and
it distinguishes the common name of the API (IndexedDB) from its member
object proper names
(IDBFactory, IDBCursor, etc.) However, with the current structure of the '''apis''' namespace, there is a problem with differentiation between API Listings and API Objects.

+

Our WPD:New_Page page provides for the creation of API Listing pages
that describe
the API
and
list all of the API objects in it
. The listing page
distinguishes the common name of the API (IndexedDB) from its member
objects
(IDBFactory, IDBCursor, etc.) However, with the current structure of the '''apis''' namespace, there is a problem with differentiation between API Listings and API Objects.



Sometimes this is problem with the case of the URL artifact. For example, the API listing should be '''indexeddb''' instead of '''indexedDB''' where the camel casing implies an object. (All lower case implies a listing - see [[WPD:Manual_Of_Style#URLs|URLs]] in the Manual of Style.)

+

Sometimes this is
a
problem with the case of the URL artifact. For example, the API listing should be '''indexeddb''' instead of '''indexedDB''' where the camel casing implies an object. (All lower case implies a listing - see [[WPD:Manual_Of_Style#URLs|URLs]] in the Manual of Style.)



Sometimes
this
is a problem with a missing '''objects''' namespace artifact
,
as in [[apis/timing/objects/performance]]. Most of the
apis
appear to missing this artifact - at least if you look at the [[apis]] page. For example, [[apis/indexedDB/IDBFactory]] would be better understood as '''apis/indexedDB/objects/IDBFactory'''.

+

Sometimes
it
is a problem with a missing '''objects''' namespace artifact
- but not always -
as in [[apis/timing/objects/performance]]. Most of the
APIs
appear to missing this artifact - at least if you look at the [[apis]] page. For example, [[apis/indexedDB/IDBFactory]] would be better understood as '''apis/indexedDB/objects/IDBFactory'''.

We need to consistently distinguish API objects the same way we distinguish events, methods, and properties, by placing the '''objects''' artifact between the API listing and object, as in [[apis/webrtc/objects/MediaStream]].

We need to consistently distinguish API objects the same way we distinguish events, methods, and properties, by placing the '''objects''' artifact between the API listing and object, as in [[apis/webrtc/objects/MediaStream]].

Show more