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."
Content layout
Summary
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.
Info boxes
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
- etc
Description/IDL box
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.
Examples
Below the description/IDL tab box is the example section; this has one or more live samples, each with a subheading and descriptive text.
Specifications
Next is the specifications section, with a table showing the specs related to the API.
Browser compatibility
The browser compatibility table and any accompanying notes comprise the final section in the article's main content area.
Sidebar
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!
Table of contents
The table of contents box grows vertically to ensure that all information is visible. By default, <h2> and <h3> should be displayed. These will be the main headings for sections and the individual function and property names within the API.
API links
This box is a list of related APIs. For example, if you're in the CSS Reference, these would be links to other CSS properties, at-rules, and so forth. If you're in the JavaScript Reference, this would be links to other global objects, the operators page, etc. In the HTML Reference, this would be a list of HTML elements.
Related
The "Related" box shows a list of related articles; this replaces the "See also" section we currently use in-body.
Languages (?)
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.