Documentation/Portal pages

Create a landing page that helps users navigate a complex topic space that spans multiple products and technologies. Provide a basic orientation to the topic, and contextualized links to more specific landing pages.

Examples

• mw:How_to_contribute
• meta:Research:Data
• mw:Localisation
• wikitech:Main_page
• wikitech:Portal:Toolforge

Description

A portal page helps users navigate a broad topic or thematic area that spans multiple products and technologies. Portal pages are cross-collection landing pages. They help users define and refine their understanding of what information they need, and how to search for it, when they're unfamiliar with the topic area, products, or technical area. Portal pages are navigation-focused. They guide users to more specific landing pages, and they help bridge the many wikis, static sites, and other repositories that host Wikimedia technical content.

Page contents

Required

Descriptive title

Because portal pages help organize and contextualize other pages, the title should be descriptive enough to make sense when viewed directly from a search engine.

Topic introduction

Briefly introduce the topic or theme of the page in the first section under the title. In a few sentences, orient the reader to where they are, the purpose and intended audience of the page, and what types of products/services the page will help them explore or find.

This section may include a link to a more in-depth topic overview, if one exists.

Create an excerpt or use partial transclusion to reuse content from other pages, like conceptual overviews, to fill in this section.

Link groupings

Format groups of links together in a way that is easy to navigate, such as Template:ContentGrid and Template:Colored box. Avoid organizing links with tables or headings.

Link groupings make it easier to scan and comprehend the content on a page. They create "meaningful, visually distinct content units that make sense in the context of the larger whole." Organize links into groups that are meaningful for your reader. Usually, this means grouping links by user group or task. Avoid general categories like "Other resources".

Links to landing pages

Link to the landing pages for the main products or technologies that the reader should know about as they gain proficiency in this topic area. Use your subject knowledge to curate a list of the most important and actively-maintained technologies in this space, not an exhaustive list.

Unlike Landing pages, portal landing pages should generally not link to content pages. One exception to this is if a #Topic overview exists at the same broad, thematic level.

Recommended

Link to a topic overview

For complex topics, users often need additional explanation to help them begin to navigate the technical landscape. In such cases, portal pages may link to a conceptual overview or topic introduction that helps beginners build their mental model of the topic space.

Examples:

• A portal page like meta:Research:Data could link to a conceptual overview that provides a high-level orientation to the Wikimedia open data landscape.
• A portal page like mw:How_to_contribute could link to New_Developers/Introduction_to_the_Wikimedia_Technical_Ecosystem, because these are targeted at the same audiences and are at the same level of specificity (they are both high-level).

Like all conceptual overviews, a topic overview at the cross-collection level covers the core concepts a user should know to help them build their mental model of the topic space and understand how to proceed in their journey.

One portal page per topic

Ideally, portal pages should be unique across all content platforms (across all wikis, static sites, other doc repos, etc.). So, for example, there shouldn't be portal pages covering the same broad topic space on both Meta-wiki and Wikitech. Part of the navigational utility of portal pages is that they are like bridges that help people navigate more easily between and across the many repositories of Wikimedia technical content.

Not recommended

Exhaustive lists of all products or technologies in a topic area

Portal pages should not link to every possible product/technology in a topic space. Providing too many links inhibits beginners from being able to identify the content they should visit next to proceed towards their goal. If a use case exists for an exhaustive list of all product landing pages in a given topic space, apply category metadata to Landing pages instead of manually curating such lists in portal pages.

Subpages

Portal pages should generally not have subpages, since they span multiple content collections and link to more specific landing pages. Those more specific landing pages provide entry to clearly-defined collections of content where subpages are appropriate.

Links to tutorials or how-to pages

Tutorials or how-to pages are specific to a product or technology. They should be linked from landing pages, but generally not from portal pages.

Content templates

template	mediawiki.org	Meta-Wiki	Wikitech
mw:Template:ContentGrid	Available	Available	Available
mw:Template:Colored box	Available	Available	Available
mw:Template:Contribution	Available	Not available	Available
wikitech:Template:Portal list item	Not available	Not available	Available
mw:Template:Navbox	Available	Available	Not available
wikitech:Template:Prefix search	Not available	Not available	Available
mw:Template:pagelang	Available	Available	Available
meta:Template:Portal navigation	Not available	Available	Not available

Related documentation templates

• Landing pages