Page MenuHomePhabricator

Review Cloud Services landing page
Closed, ResolvedPublic

Description

This task is part of a project to establish a formal review process and set of standards for Wikimedia technical documentation. For more information, visit the project page on mediawiki.org

Page

https://wikitech.wikimedia.org/wiki/Help:Cloud_Services_Introduction

Content review

What is the topic of the page?

  • Wikimedia Cloud Services

Does the page fit into to a defined content type?

  • Cross-collection landing pages

What information is included on the page?

  • Description of Wikimedia Cloud Services
  • History of Wikimedia Cloud Services
  • Descriptions of Wikimedia Cloud Services products and services
  • Instructions for signing up for services
  • Links to the terms and conditions
  • How to communicate with the Cloud Services team

Who is the audience (or audiences) of the page? Is the content of the page suitable for that audience?

  • Audiences
    • Developers who want to use Wikimedia Cloud Services
    • WMF staff who want to know what Wikimedia Cloud services is
  • There's some content that is specific to certain services, like terms and conditions and license requirements, that may not belong on this page. I'm not sure if the sign up instructions are suitable for the page or would be a better for a getting started guide. I do really like the approachable language used on the image; it would be nice to see some more beginner-friendly, task-oriented language in general.

Are there any duplicate pages that need to be merged or marked as obsolete?

How is the page linked to related pages? Is it part of a clearly defined collection of pages? Check Special:PrefixIndex for subpages.

  • No subpages
  • Links to other pages presented within text
  • Communication section transcluded frm Help:Cloud Services communication, but I wouldn't say it needs to be merged necessarily

What are the most impactful changes that can be made to improve the page? If the page is part of a collection, what are the most impactful changes that can be made to improve the collection as a whole?

  • Remove outdated "Renaming of products and services" section; cover this in "WMCS history" (covers same "Labs" aspect) and move "History" to bottom
  • "Sign up for services" implies mandatory steps; clarify that some items are WMCS team oriented (Phab; Gerrit) and not maintainer oriented
  • "Communication and support" mixes some WMCS team oriented items (Phab workboard); should clarify audience; could be a task/action oriented list of bullet points (what do I want to achieve?) instead of a table
  • The term "Products" may welcome a better term, "platforms"?
  • Rename "WMCS project overview" to "Overview"
  • Cover how Cloud Services can help me, what it can do for me (Host my tools, access PAWS, Jupyter notebook, etc)
  • [Process note] This question is a little awkwardly placed in the process. Maybe move to the end in a separate section?

Content checklist

  • Introduction: For search optimization and page previews, include a short introduction as the first text on the page following the title. This should briefly introduce the content type, purpose of the page, general audience, and topic with the goal of providing enough information to be meaningful in a set of search results.
    • Need to add this
  • Table of contents: MediaWiki automatically creates a table of contents when a page has more than three headings.[1] Use Template:TOC to limit the heading levels displayed in the table of contents so that it is meaningful and concise. (not available on wikitech!) To save space, a table of contents can be opposite the title (right-aligned in LTR languages).
    • Right-alignment would be helpful here
  • Section headings: Section headings use sentence case. Headings should use h2, h3, and h4 styles.
  • Code samples: Code samples should use template:Codesample and include a filename if appropriate.
  • Links: Links on the page go to existing, non-obsolete pages (unless for historical reasons). Link text is descriptive and does not include any wiki prefixes. Special:MyLanguage links are used whenever possible.
  • Lists: Do not use bulleted list items to complete an introductory sentence fragment.
  • Status: No draft or outdated banners are present.
  • Translation: If translation is available and the content of the page is stable, the page is marked for translation.
    • Translation not available on Wikitech
  • Mobile: The page is readable on mobile, with all important information visible.
    • The "WMCS Products" table is a bit hard to read on mobile, but otherwise looks good
  • Accessibility: The page complies with the accessibility guide for developers.
    • ✔ Image needs alt text
    • ✔ Empty header in "Communicate with us" table
  • Date format: Either write out the complete date (September 1, 2021) or use YYYY-MM-DD format (2021-09-01).
  • Descriptive title: Because landing pages help organize and contextualize other pages, the title of a landing page should be descriptive enough to make sense when viewed directly from a search engine.
    • I think something like "Wikimedia Cloud Services" might be better here
  • Topic overview: To provide context, a landing page should include a section that introduces the topic or theme of the page. For example, a landing page for Toolforge should include a section that describes what Toolforge is, what is does, and who uses it. This can be under an "About Toolforge" section or, if it makes sense with the layout of the page, in the first section under the title.
    • I'd prefer replacing "WMCS project overview" with "Wikimedia Cloud Services overview"
  • Small groups: When linking to other documentation pages, a landing page should organize links into groups of no more than six.
  • Link hub layout: When linking to other documentation pages, present groups of links in a way that is easy to navigate, such as Template:ContentGrid, Template:Colored box, Template:Contribution, Template:Portal list item on Wikitech, or a sidebar. Avoid organizing links with tables or headings.
    • Links to products are organized into a table, so this should be swapped with another type of formatting. This will also help improve the mobile view

Maintainer outreach

Is there anything notable in the recent activity? Check page views, talk page posts, and recent edits.

  • Most recent edits are vandalism and reverts; last content edit November 2020
  • Talk page has one question and answer from October 2020

Who seems to be active on or knowledgeable about the page?

  • SRodlund, BryanDavis, Quiddity, JJMC89, and Nskaggs seem to be active editors and monitors

To reach out to

  • SRodlund

To discuss with maintainers

  • Title style: Uses sentence case for titles. The title should be descriptive and specific. This helps visitors decide whether they would want to use the page. For example: "Accessing Instances on Cloud VPS" is much better than "Instances".
    • Title should be switched to sentence case. I'd also argue for something like "Wikimedia Cloud Services". Does it need to be in the Help namespace?
  • Feedback and communication: The page prompts readers to share feedback or ask a question. It indicates where readers can go to get updates or connect with others, if appropriate. A talk page exists (or redirects to a central talk page) with at least a welcome post.
    • This is well-covered by the "Communication and support" section, but we may want to consider linking directly to the talk page and adding an intro to the talk page.
    • Where are maintainers responding to questions? Are they watching the talk page?
  • Friendlier language for newcomers: Adding a section that provides quick links and some friendly, task-based descriptions

Writing style review

Review the style of the page for compliance with the [[Documentation/Style guide|Wikimedia technical documentation style guide]]. Using a writing analysis tool (like [https://www.expresso-app.org/ Expresso]) can help you identify ways to improve readability, sentence length, and other aspects of plain language.

  • Plain language: The language used on the page is clear and concise. It is free of jargon, idioms, and other ambiguous or confusing elements. Sentences are not more than 30 words in length.
  • Positive language: Avoid using negative sentence constructions.
  • Inclusive language: Use non-gendered language, and avoid the terms listed in the inclusive language guide.
  • Active voice: Use active voice, except when diplomacy calls for passive voice.
  • Second person point of view: Uses second person ("You" or assumed "You") when addressing your audience. Avoid first person ("I", "we", "our"), unless the page is an FAQ with questions asked from the first person perspective.
  • Imperative mood: Uses an imperative mood for most documentation focused on goals or process. Avoid future tense ("will").
  • Typos: The page has been reviewed for typos.
  • (Optional) Grade level check: Use a writing analysis tool (like Expresso) to check the grade level of the page (sometimes called a readability score). Strive to keep documentation under an eighth grade reading level.

Event Timeline

apaskulin created this task.
apaskulin moved this task from Backlog to Update key docs on the Key docs update 2021-22 board.
apaskulin moved this task from Inbox to Style review on the Documentation-Review-Board board.

@Aklapper I did a first pass through the questions and checklist. Let me know what you think! Feel free to add bullets to the task description

@Aklapper to fix the outstanding items in the "Content review" checklist

@apaskulin to send an initial email to Sarah R (as the maintainer) with some questions, plus set up a meeting to discuss

@apaskulin to edit style checklist, and @Aklapper to complete

@Aklapper I sent the email to Sarah R, giving her the option to set up a meeting or work async, and added the style checklist to the task

Sidenote / to follow up: https://wikitech.wikimedia.org/wiki/Portal:Toolforge/Quickstart links to https://wikitech.wikimedia.org/wiki/Help:Access_to_Cloud_VPS_instances_with_PuTTY_and_WinSCP instead of https://wikitech.wikimedia.org/wiki/Help:Accessing_Cloud_VPS_instances . I do not think that makes sense in 2022 so I changed that. The latter page should however somewhere point to the PuTTY link. There is also https://wikitech.wikimedia.org/wiki/Template:Toolforge_nav linking to https://wikitech.wikimedia.org/wiki/Help:Access_to_Toolforge_instances_with_PuTTY_and_WinSCP but no corresponding "Help:Access_to_Toolforge_instances" page seems to exist.
Those PuTTy links are e.g. in https://wikitech.wikimedia.org/wiki/Portal:Toolforge/Quickstart so should also check Special:WhatLinksHere after potentially fixing.
The CloudVPS page mentions that it's irrelevant in Windows 10, the Toolforge page does not. That's rather inconsistent and something to sync, I guess.

Heads-up to @komla as this could be an interesting read, and I welcome feedback on what's missing or bad. :)

The current idea (or experiment?) is to merge these four pages:

Whether that's really what we should do is a different question though. :P
I have a work in progress (WIP) draft now at https://wikitech.wikimedia.org/wiki/User:Aklapper/Sandbox . But it is long, and we might want to remove some stuff and push it lower into https://wikitech.wikimedia.org/wiki/Portal:Toolforge and https://wikitech.wikimedia.org/wiki/Portal:Cloud_VPS ?

Also some random further notes to myself:

Note to myself: I can imagine we might also see some Quarry/PAWS tutorial videos resulting from T292135. Potentially link them once/if existing.

The CS Intro page draft at https://wikitech.wikimedia.org/wiki/User:Aklapper/Sandbox welcomes reviews (or even bold edits!).
I also guess that some details should be pushed down into [[Portal:Toolforge]] and [[Portal:Cloud_VPS]] instead.

I made a somewhat bold edit to reduce the number of levels in the TOC and add in the topic boxes from Sarah's staging page https://wikitech.wikimedia.org/wiki/User:SRodlund/servicedecisions_(staging). I LOVE that 'which service is right for me' table.

I don't think the Getting Started page should be combined with this overview / landing page. Better to just provide clear and prominent links to that page but keep the how-to content separate from the overview and introductory content.

@TBurmeister: Thanks! And valid points! :) I agree with the thought of not having the "Get started" section content on this overview page (but instead link to the two Portal: pages). And breaking up stuff currently on https://wikitech.wikimedia.org/wiki/Help:Getting_Started (and in the "Get started" section into the https://wikitech.wikimedia.org/wiki/Portal:Toolforge resp. https://wikitech.wikimedia.org/wiki/Portal:Cloud_VPS pages though (because IMO there's quite some overlap). And then redirect (?) a pretty contentless Help:Getting_Started page.

Even if there is overlap, it seems we are funneling readers to one or the other (Toolforge or Cloud VPS), so it would be better to put the Toolforge getting started steps on the Toolforge portal / docs, and the same for Cloud VPS getting started steps going to live with those docs. Is that what you meant?

@TBurmeister: Eh, right, let me try to describe (and check if I understand correctly):

That's what I'd propose (because you're right that Getting Started should remain separate, but I also want to reduce duplication). Does that make sense?

Aklapper changed the task status from Open to In Progress.Feb 2 2022, 1:00 PM

Sounds great to me, and yes that was what I was hoping for / envisioning. We are making doc dreams come true!

https://wikitech.wikimedia.org/wiki/User:Aklapper/Sandbox looks great! I agree with Tricia's feedback and the changes proposed in this comment. One other suggestion: Keep the content, but remove the "Overview" heading, so the page starts with the text in that section "Wikimedia Cloud Services (WMCS) provides tools, services, and support..."

Aklapper updated the task description. (Show Details)
  • Title should be switched to sentence case. I'd also argue for something like "Wikimedia Cloud Services". Does it need to be in the Help namespace?

This (Help: namespace or not) is still an open question, as renaming the page (and updating redirects) is the last thing to do in this task.

"Wikimedia Cloud Services" seems like a fine title to me (with that capitalization, not sentence case, because proper nouns). I don't think the page should be in the Help: namespace but I'm not really familiar with why things may have been put there in the past, so would defer to @apaskulin for tech writer input on that.

  • Title should be switched to sentence case. I'd also argue for something like "Wikimedia Cloud Services". Does it need to be in the Help namespace?

This (Help: namespace or not) is still an open question, as renaming the page (and updating redirects) is the last thing to do in this task.

The comment about sentence case was referring to changing "Cloud Services Introduction" to "Cloud Service introduction" (lowercase "i"), if we wanted to keep that title as opposed to using something like "Wikimedia Cloud Services".

As far as the Help namespace, these are the pages currently in the Help namespace on Wikitech. For now, I think making decisions about what should be in the Help namespace is outside the scope of this work, so I think it's ok to leave this page in the Help namespace for now.

Thanks for all these great updates, @Aklapper!

Alright, I went simply for Cloud Services introduction now (non-capital I). Thanks everyone for the support (and patience).