Landing page

A landing page is a page which serves as a "jumping off point" for a given technology or topic area. Its primary purpose is to provide links to subpages or related topics. There are two basic forms of landing page, with only fairly minor differences. Most of the time, landing pages should have only a few links on them, with nested layers of landing pages guiding the user to the documentation they need. When you can't break things down, you use the second type of landing page which offers more links to the content.

Standard topic landing page

Usually one would use this style of landing page.

Descriptions of page areas


The first part of the page is a brief summary of what the landing page's content is about. Typically this is just a paragraph or two explaining the API or technology being covered. This text is used as the Google summary for SEO purposes (although you can use the CSS class "seoSummary" to specifically choose parts of it to be used if you want to really make sure the best possible text is used).

Key content boxes

Up to three small boxes follow, each serving as a large "button" connecting the user quickly to the primary information resources about the technology. These boxes are:

A link to the API's reference starting page.
A link to a page listing tutorials for the technology. These tutorials include large tutorial series as well as short guides to given areas of the technology.
A link to Demo Studio content showcasing the technology.


This box is a <dl> whose title lines are the names of articles about key concepts related to the technology, and whose definition lines summarize those articles. Typically, these will be key pages from the tutorial/guide list that can help newcomers to the technology quickly get up to speed.

What's hot

A list of the most interesting/important/exciting/new articles about the technology. Exactly how this list is generated is to be determined; this could be automated or done by hand (or some combination).

A list of off-site links to pages related to the technology.


Links connecting the reader to our community about this topic. This would include links to IRC channels, mailing lists, and so forth. For example, on the Apps landing page, there would be links to the #openwebapps IRC channel as well as the forum (or whatever it's called). This may also be where we have links to subscribe to email newsletters about the topic as appropriate.

A list of links to related technologies' landing pages. For Apps, this might be things like HTML, CSS, Games, Web APIs, and the like.

Broad topic landing page

When a topic has a lot of links, you might choose to do away with the "What's hot" area as well as the reference/demos/tutorials boxes to give more room for links to articles. This should be used fairly rarely. A good example of a place where it might be used is for the Developer Tools landing page, where there are a lot of tools to list and you can't easily break that down into subpages.


This box is a <dl> whose title lines are the names of articles about key concepts related to the technology, and whose definition lines summarize those articles. Unlike the standard landing page, this will be a complete list of articles about the topic. This box should be multi-column (probably 2) when possible.

Other boxes

All the other boxes are the same as for the standard landing page format.

Notes on the two types of page

If we go with a two-sidebar design, we could move "What's Hot" into a sidebar box, thereby simplifying the main body design. This would unify that middle section between the two layouts and simplify the editing experience. We could then have one button that adds the "Links" and "Community" row to the page and another for the "Related Topics" box.

The sidebar includes the Edit and History buttons, as well as the following boxes.

Recent changes

This box shows a list of articles that have been changed recently. We should consider carefully ways to filter this list to only show "interesting" changes.


This section examines the editing experience for landing pages.

Note: We will probably want to establish a privilege group for editing of landing pages. In fact, probably two groups: one group that has privileges for editing any landing page, and then another group with per-landing page privileges, to allow configuration of people with special permission to edit given zones' landing pages. This will let us give product managers for given topic areas permission to edit their topic's landing pages.

Editing notes

  • There is nothing on the sidebar(s) on landing pages that the user needs to be able to edit.

Editing features needed

Toolbar buttons

Add key content box
This button would add a box to the row of key content boxes below the intro text. This should put the box there regardless of where the user is currently writing. I'd suggest having a popup that asks where in the row to insert the box (at the beginning or end), what title to give the box, what text to put in the box, and where the box should link to. The entire box should serve as a link to the destination page.
Add "Links" and "Community" row
This button would add the "Links" and "Community" boxes to the page below the main content area. Only one of these rows should be allowed on the page.
Add "Related topics" box
This button would create the "Related topics" box at the bottom of the page. Only one such box is allowed per page.
Definition list buttons
We need the buttons for creating <dl> elements, as well as for <dt> and <dd>. We also need to be sure that editing of and deleting these works reliably (it can be a little quirky right now) if we want to remove source editing eventually; currently you have to resort to source mode sometimes to fit problems with the lists.
Bullet list button
We need a button for creating <ul>s, for the offsite link list, for example.
Insert image button
We need to be able to insert images, to use a product or technology logo somewhere on the page (most likely in the intro area).
Link/unlink buttons
We need to be able to create and remove links.
Bold/italic buttons
We should allow creating bold and italic text.
API/function name button(s)
We need buttons for styling text as the name of a class/interface/function name. Ideally these would have different classes on the <code> element for the different types of these, and would automatically create the appropriate link to that term's page, but that may be a long-term goal.

Other features

  • Ability to easily delete key content boxes; removing divs can be tricky, so be sure it works reliably.

Editing features NOT needed

There are things we expressly do not want to have available in the editor:

  • Blockquote
  • Tables
  • Foreground/background color
  • Code samples
  • <pre>
  • Underline
  • Anchor
  • Justification (left/center/right)