Developer Portal/Content strategy

This page includes guidelines for content on the Developer Portal.

Content types[edit]

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 src/index.md.
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 src 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 data 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 src/get-help/about.md.

Information architecture[edit]

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

The following outline has been manually created and may be out of date. For the latest structure, see the src directory

├── Homepage
├── Get started
│   ├── Learn about Wikimedia technology (category: wikimedia-tech)
│   ├── Understand the development process (category: new-dev)
│   ├── Learn with tutorials (links: build-tools/tutorials, use-content/tutorials)
│   └── Browse by programming language (documents: client-libraries, repos; link: contribute/by-language)
├── Use content and data
│   ├── Explore featured apps (category: app-galleries)
│   ├── Learn with tutorials (category: tutorials-use)
│   ├── Use wiki content (category: use-content, document: enterprise)
│   └── Access open data (category: access-data)
├── Tools and bots
│   ├── Discover and share tools (category: search-tools)
│   ├── Get started (category: get-started-tools)
│   ├── Learn with tutorials (category: tutorials-tools)
│   ├── Use APIs and data sources (category: apis-tools)
│   └── Host tools on Wikimedia servers (category: toolforge)
├── Contribute to Wikimedia open source
│   ├── Learn how contributing works (category: new-contributor)
│   ├── Contribute by topic (category: contribute-by-topic)
│   ├── Contribute by programming language (categories: contribute-[language])
│   └── Search all projects (category: search-projects, document: toolhub)
├── Community
│   ├── Explore hackathons and events (category: events, document: small-wiki-toolkits)
│   ├── Communicate with the tech community (category: communicate)
│   ├── Learn and share technical skills (category: grow)
│   ├── Get tech project updates (category: updates)
│   └── Learn about Wikimedia technical operations (category: wikimedia-tech-operations)
└── Get help (category: help)
    └── About

Content patterns[edit]

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

Signpost[edit]

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[edit]

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 /Special:MyLanguage. 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.

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"

Wormhole[edit]

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 ({ .md-button }).

Navigation[edit]

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[edit]

The text in the navigation bar, sidebar, and navigation drawer is set in mkdocs.yml using the nav key.