Developer Portal/Content strategy

This page includes guidelines for content on the Developer Portal.

Content types

 * Homepage
 * The main site landing page, including a headline and description, call to action, and links to each section. The content of the homepage is defined by.


 * Section landing pages
 * Top-level pages that link to subpages. Each section landing page represents a critical user journey. The titles of these pages appear in the navigation bar. The content of a section landing page is defined by an index.md file in the corresponding subdirectory within the directory.


 * Subpages
 * Pages within a section that link out to relevant documentation pages and resources. Each subpage has a corresponding markdown file that defines which categories and documents from the directory appear on the page.


 * About page
 * Contains a brief summary of the site, and links to on-wiki docs. The content of the homepage is defined by.

Information architecture
The Dev Portal is organized based on critical user journeys identified for core audiences.

Content patterns
The Dev Portal uses the following patterns to present and organize content.

Signpost


A signpost is a heading, link, and description that helps users make choices within the Portal about which content is relevant to them. Signposts provide a way to choose a user journey and select tasks within a user journey. Signposts are used on the homepage and section landing pages.


 * Image (optional)
 * On the homepage, each signpost is accompanied by an image from the adapted Wikipedia 20 graphics. This helps break up the text and aid visual learners. Signposts elsewhere on the site do not include images, but images can be added as long as they are consistent and work with both light and dark modes.


 * Heading (required)
 * A signpost must include a level 2 heading that doubles as a link. Heading text must be short and match the title of the page it links to. This is especially important when the heading and the page title are visible at the same time, such as in the sidebar. Heading text should focus on the task the user is trying to achieve. Avoid unspecific titles like “Best practices”. In most cases, start a heading text with a verb.


 * Description (required)
 * A signpost must include a descriptive sentence that provides context to help users decide whether the content is relevant to their goals. Descriptions must be one sentence long and start with a verb. Try to avoid repeating the same verbs multiple times on a page.

Resource


A resource is a heading, description, and one or more links to documents outside the Dev Portal. It connects the user journeys in the Portal to documentation that helps users complete their tasks. Resources are used on subpages and must not be used on landing pages.


 * Heading (required)
 * A resource must include a level 2 heading that uses key words that users are looking for. If multiple categories are used on a page, resources headings should be level 3. Resource headings should be short and, in most cases, start with a verb.


 * Description (required)
 * A resource must include descriptive text that provides context for the links. Resource descriptions should be 1-3 sentences long and free of filler words and status information.


 * Links (required)
 * A resource should link to one or more documents that help users achieve a task within a user journey. Links to mediawiki.org and Meta-Wiki must include . In most cases, a resource should have only one link. However, in some cases, additional links are appropriate if they belong to the same collection and provide a useful shortcut. Links should point to the top of the page, not to a specific section.
 * {| class="wikitable"

! Link type !! Link text
 * For wiki pages || Use "Read more on mediawiki.org", "Read more on Meta-Wiki", or "Read more on Wikitech"
 * For apps || Use "Visit [app name]". For example, "Visit Toolhub".
 * For source repositories || Use "Get the source code"
 * For contributing guides || Use "Contribute"
 * For microsites and other exceptions || Use "Read more" or a relevant action such as "Browse repositories on GitLab"
 * }
 * For contributing guides || Use "Contribute"
 * For microsites and other exceptions || Use "Read more" or a relevant action such as "Browse repositories on GitLab"
 * }
 * For microsites and other exceptions || Use "Read more" or a relevant action such as "Browse repositories on GitLab"
 * }

Wormhole


A wormhole is a shortcut between tasks in a user journey. Wormholes are used on subpages and must not be used on landing pages.


 * Heading (required)
 * A wormhole must include a short, task-oriented level 2 heading.


 * Description (required)
 * A wormhole must include a descriptive sentence that provides context to help users decide whether the content is relevant to their goals. Descriptions should be one sentence long and, in most cases, start with a verb.


 * Button (required)
 * Instead of a link, a wormhole uses a button to indicate a jump outside the standard navigation patterns of the site. All buttons should use the default button style.

Navigation
Navigation elements help users switch between pages and understand the structure of the site.


 * Navigation bar
 * The navigation bar is visible at screen widths 1220px and larger. It links to each section landing page. To limit cognitive demand, the navigation bar should include no more than seven links.


 * Sidebar
 * Like the navigation bar, the sidebar is visible at screen widths 1220px and larger. It links to each page in a section and, for subpages, each heading on the page.


 * Navigation drawer
 * The navigation drawer replaces the navigation bar and sidebar at screen widths 1219px and smaller.


 * Search
 * The search box searches all text in the Dev Portal in all available languages.

Configuration
The text in the navigation bar, sidebar, and navigation drawer is set in using the   key.