Page MenuHomePhabricator

Revise: Help:Cloud_Services_introduction
Closed, ResolvedPublic

Description

Current page:
https://wikitech.wikimedia.org/wiki/Help:Cloud_Services_introduction

Draft: revision:
https://wikitech.wikimedia.org/wiki/User:Triciaburmeister/Sandbox/Cloud_Services_introduction

TODO:

  • Resolve TODOs via interviews with SMEs
  • Copyediting
  • Layout and visual design improvements
  • Tech writer peer review
  • SME / WMCS team member review
  • Replace current page with new revision
  • Update incoming anchor links where feasible

Event Timeline

TBurmeister changed the task status from Open to In Progress.
TBurmeister triaged this task as Medium priority.

I'd probably also remove that lonely PAWS logo duplicating the first link in the section, and those two logos linking to the {Cloud_VPS|Toolforge} portals without any indication that they do so (and those links are already under "Learn more")

Reiterating my earlier feedback that I really like the way the headings provide a summary of the page and act to contextualize the explanation of the products. Here are my suggestions, acknowledging the fact that not all this feedback applies specifically to the changes you made:

  • For consistency with the keyword bolding style used in the rest of the page, I suggest bolding "Wikimedia Cloud Services" in the first sentence.
  • In "Toolforge provides the following features for developers who support Wikimedia projects by developing tools, bots, web services, or scheduled jobs:", it's too much to introduce a list and then have another list before starting the first list. "For developers who support Wikimedia projects by developing tools, bots, web services, or scheduled jobs, Toolforge provides the following features:" would fix this. This frontloading would also be nice in the intro sentence to the first bulleted list under "Administer servers for software development".
    • Additionally, I'm unsure about "web services" in this list; is it too broad to be meaningful? is it more of a how than a what? is web service to tool as scheduled job is to bot? Should it just be "tools and bots" since those are the primary "what" categories?
  • In the first three bullets under "Host tools on Wikimedia servers":
    • What does "shared" mean here?
    • I prefer to remove "platform as a service" since it's jargon-y. (When you mention this later, I think it's ok because you're linking to Wikipedia and using the terms to provide extra clarity at a very detailed level of explanation.)
    • What does "distributed" mean here? Is it necessary for users to know?
    • "Support for multiple users to collaboratively manage software source code, configuration, and jobs for a tool or bot." This is a lot of words to say that you can have multiple maintainers for a tool. Could we simplify this or say it more directly?
  • You don't strictly need to understand "Version control via Gerrit and Git" to use Toolforge. It is certainly a best practice, but it's not provided out-of-the-box with a new tool. I suggest removing it from this list since fewer requirements are better. If you want to keep it, GitLab is now the default for tools. (The create a repo button goes to GitLab.)
  • Maybe instead of linking to https://www.mediawiki.org/wiki/Manual:Creating_a_bot, link to https://developer.wikimedia.org/build-tools/?
  • The link on "other data storage" goes to a section on Help:Toolforge that doesn't exist.
  • In the "Run scripts and create tutorials" heading, replace “create tutorials” with “visualize data” since creating tutorials isn't a primary use case of jupyter notebooks.
  • Link Wikimedia login to https://meta.wikimedia.org/wiki/Help:Unified_login
  • Maybe a callout format would be nice for the "What is a wiki replica?..." line
  • The link to Help:Getting Started seems to create the kind of link loop you had talked about avoiding with the new IA. That page also prompts users to go through the Gerrit tutorial, which is a pretty heavy lift and may not be necessary for them. Are you planning to modify that page? Should we link to Help:Create a Wikimedia developer account instead?
  • I think I would prefer this page without the right-aligned logos. The alignment can get a little funky in some places (the Quarry logo looks like it's part of the Which service is right for you? section), and I don't think they're providing a lot of value or making the page easier to skim.
  • I assume that you'll remove the Tracked in Phabricator template before publishing, but adding a note here that I don't think it's needed on the final page.

Update links for creating a developer account to go to https://idm.wikimedia.org/signup/ instead of Wikitech pages

TBurmeister updated the task description. (Show Details)
TBurmeister moved this task from Waiting for feedback to In progress on the Tech-Docs-Team board.
TBurmeister added a subscriber: apaskulin.

There is definitely an issue with link loops between:

Help:Getting Started
Help:Create_a_Wikimedia_developer_account
Help:Toolforge/Quickstart
and now
https://idm.wikimedia.org/signup/

I'll address that when I work on T344637, and will circle back to this and other pages to make sure they link to a non-frustrating account creation getting-started page.

TBurmeister updated the task description. (Show Details)

Updated incoming links on a few Wikitech pages; added heading anchors so any incoming links using the old section names will still work; confirmed that use of https://wikitech.wikimedia.org/wiki/Help:Cloud_Services_introduction in Developer Portal is still a valid link in its page context.

Update: I filed a separate task for the work on the link loops and duplicate content around account creation in Cloud Services docs: https://phabricator.wikimedia.org/T346384