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[edit]
- mw:How_to_contribute
- meta:Research:Data
- mw:Localisation
- wikitech:Main_page
- wikitech:Portal:Toolforge
Description[edit]
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[edit]
Required[edit]
Descriptive title[edit]
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[edit]
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.
Link groupings[edit]
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."[1] 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[edit]
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[edit]
Link to a topic overview[edit]
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[edit]
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[edit]
Exhaustive lists of all products or technologies in a topic area[edit]
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[edit]
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[edit]
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[edit]
| 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 |