Page MenuHomePhabricator

Analyze landing page coverage from DevPortal and create framework to make landing pages more consistent
Closed, ResolvedPublic


This task captures work to:

  1. Identify where we have landing page gaps for critical user journeys that span product/tech areas.
    • These are the high-level user journeys that are the primary focus of the Developer Portal, so this work is scoped to focus on that, though the findings will be relevant for other high-level entry points that exist, on-wiki or elsewhere.
  2. Create a framework for when a landing page should exist, and what it should cover.
    • For example: when a project involves producing multiple pieces of technology, how should the documentation for that project and those technologies be structured? Should the project have a landing page along with each of the technologies? Or one and not the other? How can the landing pages that help people navigate into our technical content be flexible enough to align with changing realities, but persistent enough to be reliable and usable over time, regardless of changing project or organizational weather?
  3. Design and publish templates for the different types of landing pages that we think should exist based on this analysis.

Event Timeline

Status update:

    • working on analyzing existing landing pages for the user journeys around "using open data" and "hosting tools on Wikimedia servers".
  • categorizing the resources we link to from the dev portal for those journeys and identifying which of them meets criteria for a good landing page and which indicates a need for a better landing page to be created or curated
  • made initial progress with a proof of concept for taking using existing landing page content to identify the user journeys its actually serving and rewriting it to be more task-focused
  • iterating on a conceptual model to see if it can help us consistently define 1) which types of doc collections need landing pages and 2) what type of content should go on their landing pages.
TBurmeister changed the task status from Open to In Progress.Jul 10 2023, 9:22 PM

Rescoping of this task to hopefully make it more clear and finishable:

  • [started ] Identify a basic (small!) set of types of landing pages, for example: task/goal-focused landing pages, technology/software-focused landing pages, product/project-focused landing pages.
  • [started ] Finish categorizing all the pages that we link to from the Developer Portal.
    • Goal: have insight into where we're linking to which type of landing pages, and where we link directly to content pages or other non-landing pages. Ideally, we should have consistent logic for where and when we link to each type of content. This activity will help tech writers identify (even more) future tech docs priorities, because we'll have a clearer picture of which products/technical areas lack task-focused landing pages.
  • [not yet started ] Design and publish templates for each type of landing page, to help define what it should and should not cover. This should integrate and build on
    • Goal: start to move us away from having multiple landing pages that approach the same topics from different angles, but which link to each other, cover the same content, and leaving the user in confusing navigational loops. Different types of landing pages have reason to exist, but we need to clarify the purpose of each so we can ensure the content serves its purpose and doesn't waste users' time.
TBurmeister updated the task description. (Show Details)
TBurmeister renamed this task from Content mapping: identify missing landing pages for critical user journeys to Analyze landing page coverage from DevPortal and create framework to make landing pages more consistent.Jul 10 2023, 10:19 PM

Status update:

Now: working on creating new doc templates for cross-collection landing pages and conceptual overview docs.

Case study for applying these ideas: I revised the Cloud VPS and Toolforge documentation landing pages and portals to follow a stricter and more consistent content framework.

Portal pages:
Navigation focused. Minimal text content, ideally only to provide immediate context in the form of an introductory sentence or two. Use buttons or other layout tricks to make navigation quick and easy. There should be only one link to click per unit of information.

  • In the case of Toolforge and Cloud VPS, the portal pages are providing navigation between the user docs vs. the admin docs, so these are product-level portal pages. Consequently, I could transclude the intro sentence from each product's landing page to prevent duplicate or excessive product description on the portal pages. I removed the Toolforge navigation sidebar from the Toolforge portal because the nav menu serves as a tool for navigating within a a collection of docs, while the portal page serves as a tool to navigate TO the collection.
  • In the case of, the portal is providing navigation between multiple types of documentation collections, each of which may be product-, team-, audience-, or topic-focused. Portals or navigation tools at such a high level, spanning many complex content areas, require case-by-case information design. Ideally, that design work should prioritize the needs of the different audiences and user journeys to drive the content structure.
  • Antipattern / counterexample: is not actually a portal page. It has too much text and requires too much reading and comprehension before navigation can happen, and there are multiple links per information unit.

Landing pages:
See for the outline of what these are and are not, should/shouldn't contain. Examples from my recent work are:
These are both product/technology landing pages. In upcoming projects I'll likely be working on some topic- or task-focused landing pages, and will continue to refine this framework and its related artifacts.

TBurmeister closed this task as Resolved.EditedOct 4 2023, 5:57 PM

On-wiki summary of landing pages to which the Developer Portal links, and my attempt to identify the organizing principle behind them:

I also noted the pages we link to that are more like portals than landing pages, and did a full doctype categorization of all the pages we link to from the dev portal: (google spreadsheet, restricted access but i can publish more of the info on-wiki if anyone cares)