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?

• ✔ Help:At a glance: Cloud VPS and Toolforge has some overlapping content
• Interwiki direction from Wikimedia Cloud Service on mediawiki.org and Wikimedia Cloud Service on Meta, leave as-is
• ✔ Searched for "Labs" and found https://www.mediawiki.org/wiki/Welcome_to_labs, moved to User space

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.
  • ✔ "Glossary" and "List..." links should not be capitalized mid-sentence
  • ✔ https://foundation.wikimedia.org/wiki/Archive:Volunteer_opportunities marked as out of date
  • ✔ https://wikitech.wikimedia.org/wiki/Dumps.wikimedia.org could probably be replaced with https://meta.wikimedia.org/wiki/Data_dumps
  • ✔ "mw:Gerrit/GitHub/GitHub" should go to "mw:Gerrit/GitHub" with link text "GitHub"
  • ✔ We might want to replace the link to https://www.mediawiki.org/wiki/MediaWiki_on_IRC with https://wikitech.wikimedia.org/wiki/Help:IRC
  • https://www.mediawiki.org/wiki/Wikimedia_Labs/Agreement_to_disclosure_of_personally_identifiable_information is marked as a draft
• 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.