Page MenuHomePhabricator

Update Toolforge docs structure and landing pages
Closed, ResolvedPublic


This subtask is for tracking work specific to the user-facing Toolforge docs, since that collection diverges from the Cloud VPS docs and is of higher priority.


  • Research and design initial prototype of task-focused information architecture for Toolforge content
  • Initial content audit and identification of major docs tasks and new content pages needed
  • Present initial design to stakeholders and iterate on it
  • Start feedback cycle with larger community
  • Create / revise landing pages
  • Create / revise navigation template
  • File phab tasks for non-landing-page doc edits

Event Timeline

TBurmeister changed the task status from Open to In Progress.Jul 7 2023, 4:41 PM
TBurmeister triaged this task as Medium priority.
TBurmeister renamed this task from Update Toolforge doc structure and landing pages to Update Toolforge docs structure and landing pages.Jul 7 2023, 4:53 PM

As part of this project, I have the following drafts and proposed revisions ready for review and feedback:

Portal:Toolforge page
To improve and streamline the navigation of Toolforge docs, I would like to revise Portal:Toolforge so that it functions only as a navigation page, with the sole purpose of directing people to either the Toolforge user docs or the Toolforge admin docs. It basically functions that way now, but could do so more effectively if we:

  1. Remove the current user-focused navigation template and the Communication template from this page.
  2. Limit the page to only a short description of Toolforge, and links to either the user-focused landing page or the admin docs landing page.

Here is a draft revision.

Toolforge user docs navigation

  • Draft of a revised navigation template for Toolforge User docs. This revised navigation:
    • Replaces the current nav structure with task-focused groupings and link text, so that users can easily identify which documents or site sections will help them do a thing. Aligns the collection structure with the high-level tasks in the development user journey.
    • Improves the visibility of Toolforge-specific data services content ("Access shared storage and databases" section).
    • Enables to be revised to function as a more robust landing page, instead of mostly functioning as a navigation tool. I will be drafting and implementing that revision, and will post a draft in this task and on the page's Talk page when it's ready for review.

For convenient reviewing, here's a link to a Google Drawing image, with a side by side of the current Toolforge nav and the new one I'm proposing.

Toolforge admin docs navigation

Collection search issue
The doc search in the new admin nav template uses the Portal:Tool prefix for search, while the one on the user docs nav template uses Help:Tool to provide search scoped to that collection. Splitting the docs into clearer collections and implementing the new admin nav template should enable me to resolve T342287. I just need to move some user docs to be Help: subpages if they're currently Portal: subpages. (see the list in T342287).

Feedback and input on these proposed changes is most welcome! You can leave feedback on this Phab task or on the Talk pages for any of my Sandbox drafts. Thanks!

I've just published a wiki page with links to all the page revision drafts I've completed so far, and the Toolforge-specific navigation changes / information architecture:

Note: I have yet to do outreach to get input on my proposed revision for Wikitech:Main_page, but that's larger than the scope of this task so I'll handle it under the parent task.

New nav templates are now live. Changes to landing pages are also live, but I'm waiting on a final copyedit review and need to check and update incoming links before closing out the last tasks for that.

Change 956500 had a related patch set uploaded (by Triciaburmeister; author: Triciaburmeister):

[wikimedia/developer-portal@main] content: update Toolforge doc links

Change 956500 merged by jenkins-bot:

[wikimedia/developer-portal@main] content: update Toolforge doc links

TBurmeister updated the task description. (Show Details)

Phab tasks that I'm filing for doc work that I identified as part of this project, but which was out of scope, are gathered as subtasks under