A reference overview page, or "technology page", is the root page for a particular interface, class, or object. For example, the following would be considered "reference overview pages."
The page begins with a summary explaining the interface, object, class, or CSS property being described. This should be a paragraph or two at most, and is used as the SEO summary (which can be overridden using the "seoSummary" CSS class.
Depending on the topic area being covered, there may be informational boxes about the API displayed here. For example, CSS Reference pages have the summary box that displays information about usage context, initial value, and so forth. The exact content of these boxes will vary from API to API, but they will be styled similarly.
See API info boxes for mockups and descriptions of the various boxes that can appear here. These can include:
- CSS property summary
- XPCOM interface compatibility diagram
The next part of the page is a box with two tabs. The first tab (which is the default) displays a textual explanation of the API, including
<dl> lists of the methods, properties, and so forth provided by the API. Each of those is linked to a subpage specifically documenting that method, property, or other term.
The second tab displays the WebIDL defining the API.
Note: If the API doesn't have corresponding IDL, there should be no tabs here, just the text directly.
Ideally, it will be possible for users to customize in their preferences which box is the default, so that advanced users that prefer to read the IDL directly default to that tab.
Below the description/IDL tab box is the example section; this has one or more live samples, each with a subheading and descriptive text.
Next is the specifications section, with a table showing the specs related to the API.
The browser compatibility table and any accompanying notes comprise the final section in the article's main content area.
As is the case with all pages, the sidebar ideally does not scroll with the body content. We need to figure out the best way to present this; the UX team will be helpful here!
The table of contents box grows vertically to ensure that all information is visible. By default,
<h3> should be displayed. These will be the main headings for sections and the individual function and property names within the API.
The "Related" box shows a list of related articles; this replaces the "See also" section we currently use in-body.
Should we have a list of languages available for the page in the sidebar for easier discoverability? The drawback is this would take up valuable space.