Archive of obsolete content

Page types

Draft
This page is not complete.

Note: This is a working document, and not yet an official guide to anything about MDN. Don't refer to this unless you're helping to actually come up with the new MDN design guide. Thanks!

Before working on the MDN style guide (and the redesign that goes hand-in-hand with it), we need to figure out what types of pages we have, then what those pages look like. This is a list of the types of pages and key attributes of those pages.

This exercise serves multiple purposes:

  • We want to figure out what kinds of content we already have.
  • We need to standardize the layouts for each type of content.
  • Ideally, we'd like to keep the number of different page types to a minimum. If we can standardize our different sections of content to a unified look and feel, everybody wins (although it might mean some serious work in the short-to-mid term).
  • We need to figure out what CSS we need in order to build each type of page.
  • Once we've figured out the styles and layouts, we can provide master pages (page templates) for each type of article, improved editing experience, as well as documentation about how to properly construct each kind of article.

For each type of page, some examples of what they currently look like are provided. In addition, a list of features of that type of page is provided.

We will be iterating over this material to figure things out from a documentation requirements standpoint, then working on actual designs for how these pages should look. This will be done by the documentation team in concert with the web design team.

General notes

  • Ideally, we should have a way to let the user customize what content they see based on how far back they want to be compatible; for example, if a user doesn't care about anything prior to Firefox 8, don't show them stuff that was removed in Firefox 7 and earlier. We could do this by using the HTML data-* attribute to mark blocks of content with compatibility information.
  • We can similarly use data-* attributes to mark content as needing special review?
  • Unless otherwise noted, pages should always have an in-page table of contents.
  • The breadcrumbs bar should provide drop-down menus linking to other pages at each level of the hierarchy. See Breadcrumb bar for details.
  • Pages about open web technologies shouldn't use banners and badges to indicate compatibility information. This should be presented in the compatibility table at the end of the page unless absolutely necessary.
  • Use visual cues on the entire page to help remind the user if they're looking at an obsolete article or one about a non-standard or experimental technology. These cues might include a background color and/or pattern, vertical stripe on the page, and/or a combination of these or other things.
  • Support for making text areas multiple columns (when the device warrants it) would be useful.

Standard boxes

There are a few boxes or blocks that we will use on a wide variety of types of pages:

Note
An aside indicating useful or important information that deserves special attention.
Warning
A very important message that could have serious consequences if ignored.
More details
A callout box that's used to provide additional information that may be interesting but not required in order to understand the article's content.

Live sample layouts

Most of the time, live samples are displayed with the code using the full width of the text area of the page and the rendered output being allowed to be that wide as well. However, there are some additional cases:

  • Display the live sample output on the left and a screenshot of what it should look like on the right.
  • A grid of multiple live sample output boxes side by side and/or one above the other; useful for showing the output of several different uses of a CSS property, for example.

Images

Do we want to encourage the use of captions on images? Should images be displayed, by default, with some kind of attractive frame to contain and connect the image and its caption? We have to be sure that images don't hurt accessibility.

Tables

We have several tables we want to support. We want them all to use the same style.

  • Typical in-article tables
  • CSS property summaries
  • Element usage context
  • Side-by-side live sample/screenshot output
  • Compatibility tables
  • Specification tables

Creating pages

When the user is creating a page, we want to provide a preformatted boilerplate based on the type of page they're creating. Ideally, we will intelligently select the type of page and apply the right boilerplate, based on the URL at which they're creating an article. For example, if the page is at .../Reference/<x>, we know that the page is a main API page. If it's at .../Reference/SomeObject/<y>, we know it's an API term reference page.

When in doubt, we ask. And the user should be able to change it if it's wrong, using some control in the editor (although obviously this won't work once content is added; we should figure out the best approach there).

Based on the type of page the user is editing, the editor toolbar should be customized to offer appropriate features, such as buttons to insert boxes and other items specific to that type of page.

Also, ideally, pages will automatically be given appropriate tags based on where they are in the hierarchy. A page at .../HTML/Reference/<z> would automatically get the tags "Reference" and "HTML", for example. It may be that there are even more that will be appropriate, but this is a great start!

Specific questions for the UX team

  • On pages that have both a TOC and a list of links to other pages in the same document set (such as the HTML Reference, where we want a list of links of all the elements in the sidebar), what about having two tabs in the sidebar, one for the TOC and one for that element list, so we don't have to show both at once?

Other design materials

We have other design items and mockups not expressly related to page types. See:

Ribbons
Our idea for how to label content as to its specific compatibility, as well as to show things like "review needed" on smaller sections of content instead of an entire article.
Sidebars
We want one (and maybe two) sidebars with page meta-data and controls.
Quick link lists
Among the things that should appear in the sidebar are these lists of quick links to other terms in the same API; for example, if you're viewing a page in the HTML Element reference, this list would be a list of all HTML elements.
Breadcrumbs bar
The breadcrumbs bar, used to navigate the hierarchy backward, could be expanded to offer quick access to other subpages throughout the hierarchy.
Editor requirements
Information about general requirements for content editing. Additional, more specific, information for each page type is included in each page type's description page.

Landing page

A landing page is basically a "main menu" for all of its subpages. Currently, these are almost all hand-built, but might in the future be automatically generated (we're doing some experiments with this now).

[Jean-Yves] I'm currently experimenting with a second kind of landing pages, aimed at less broad technology. I think the main landing page should still be used for really broads domains like HTML, CSS, Games, Firefox OS user experience, Mobile Web, … But these simpler landing pages may be more adequate for some APIs like Web Audio (I did the test here: https://developer.mozilla.org/en-US/docs/Web_Audio_API ), WebRTC, DOM, Vibration API, Performance API, … But I still need to conduct more tests (I want to test with WebRTC and DOM).

Examples

Attributes

  • Must use responsive design to make best use of available space; should be columnar layout as possible.
  • No tables of contents, ever.
  • Typically have multiple sections for things like "Documentation", "Tools", "Community", and so forth.
  • Presents links to related articles, which are usually (but not always) subpages. Sometimes related pages are shared among several topic areas.
  • Each link should also include a brief summary of the article's topic area along with it.
  • The "Related pages" area in the sidebar might refer to related technology areas' landing pages.
  • Should typically only link to one sublevel of its content; if subpages have more subpages, don't go deeper than that.
  • May have boxes headlining key articles.
  • A link should be provided to take the user quickly to a list of all pages tagged appropriately based on the topic; for instance, the CSS landing page would offer a link to the list of pages tagged "CSS".
  • Items may be labeled as pertaining to specific versions or products.

Styles needed

Table of contents page

A table of contents page is a special type of landing page which serves as a TOC for all the articles in a multi-article document, such as the JavaScript Guide. This is, in essence, the TOC for a single multi-chapter document.

This can also include A-Z indexes of articles, such as the CSS Reference landing page; these are generally displayed (on desktop) with many columns to optimize space usage.

Examples

Attributes

Similar in many respects to landing pages, but not usually divided into sections. Instead, this is just a hierarchical list of links.

  • Can use responsive design for layout.
  • Toolbar should make linking easy
    • Link and unlink buttons
    • Buttons for common link creation macros (domxref, cssref, etc)
    • Support for inserting automatically generated lists of subpages
    • Support for quickly setting the number of columns
  • No TOC for the page itself.
  • Mostly just a hierarchical list of links.
  • Ideally automatically generated, or generated using templates.
  • May have a "next page" button to take you directly to "Chapter 1", for TOCs of article series.
  • Related pages sidebar may be a list of the top-level chapter links for the reference or guide.

Styles needed

Article page

An article is any article that explains or teaches something. These are non-reference pages which are also not landing pages or TOCs. Articles typically involve prose possibly interspersed with code snippets, live samples, and/or screenshots or other images. Article pages include, for example, tutorials, guides, and how-to documents.

Note: To assist people that skip around through tutorials, each article in a multi-part tutorial series should begin with a list of prerequisites, both of what the user should know and of what code they need. If part 3 of a series builds upon the code from part 2, part 3 should begin with a link to download the completed code from part 2.

Examples

<add examples>

Attributes

  • Need to be able to mark chunks of content as being relevant to particular products or product versions; for example, if the user needs to take special steps to work around a difference in functionality on Safari, there needs to be a way for the author to mark the text explaining this so that it's clearly labeled to the viewer. See the information elsewhere on ribbons.
  • Support for the live sample system (insert code snippets, insert the sample display iframe). Need to be sure we can have multiple samples per page easily; currently it's easy for things to get confused because there's no way to edit the names used to select the code for each sample.
  • For tutorials that are broken across multiple articles, we need a good interface for following along the chain of articles; this could be one or more of forward/back buttons, a sidebar list of the articles in the series so you can jump around, etc. We should provide easy UX for creating and managing these features.
  • Include support for embedded video for presenting screencasts or demos of technology that may only be available on a limited number of browsers.

Styles needed

Reference overview page

A reference overview page (or "technology page") is the main page for an API; this describes an interface or object which has a collection of properties, methods, or fields. The reference page describes the API in general and provides links to the subpages documenting each of the API's methods, properties, and so forth.

Examples

Attributes

  • A compatibility section; we need to make compatibility information as easy as possible to construct.
  • Need to be able to mark chunks of content as being relevant to particular products or product versions; for example, if the user needs to take special steps to work around a difference in functionality on Safari, there needs to be a way for the author to mark the text explaining this so that it's clearly labeled to the viewer. See the information elsewhere on ribbons.
  • Support for the live sample system (insert code snippets, insert the sample display iframe). Need to be sure we can have multiple samples per page easily; currently it's easy for things to get confused because there's no way to edit the names used to select the code for each sample.
  • Lists of the methods, properties, and so forth that make up the API. One section for each type of API, with a list of the items, each with a brief description and a link to the corresponding subpage that provides details.
  • For interfaces or classes that inherit from another, use Template:Page to transclude content, with an appropriate heading. For example, if nsIFoo inherits methods and properties from nsIBar, the nsIFoo page's "Methods" section should have a subsection "Methods inherited from nsIBar" whose contents are inserted using {{page("/en-US/docs/Mozilla/XPCOM/Interface/nsIBar")}}.
  • Let's see if we can come up with a way to suggest an exercise to do, hiding the answer to display when the user clicks a "Show me how" button. This could be done with a separate page, but having hidden content in the same page would be nicer.

Styles needed

Reference page

A reference page is a page that describes an individual method or property in an API.

Examples

Attributes

  • A compatibility section.
  • Syntax description.
  • Parameter list (for methods)
  • Possible values (for properties/attributes)
  • Need to be able to mark chunks of content as being relevant to particular products or product versions; for example, if the user needs to take special steps to work around a difference in functionality on Safari, there needs to be a way for the author to mark the text explaining this so that it's clearly labeled to the viewer. See the information elsewhere on ribbons.
  • Support for live samples.

Styles needed

Tabular data pages

Some pages are database tables that are reused through the transclusion to display coherent information in multiple pages. These should stay as tables and should be easy to edit. They're not typically intended to be read directly by end-users.

Examples

Attributes

  • Put table editing controls in the toolbar for adding and deleting rows, columns, etc.
  • Should not allow any information outside the table itself.

Styles needed

Template page

MDN templates are chunks of JavaScript code that are executed server-side and can be used to automatically insert content into pages as they load.

Examples

  • https://developer.mozilla.org/en-US/docs/Template:FXOSUXLiveSampleSetup
  • https://developer.mozilla.org/en-US/docs/Template:BugTableRow

Attributes

  • Contents are entirely KumaScript code.
  • Use a custom editor for code.
  • Should offer links to the KumaScript documentation while editing.

Styles needed

Document Tags and Contributors

 Contributors to this page: jswisher, Sheppy, Debapriyo, teoli, markg
 Last updated by: Sheppy,