Page MenuHomePhabricator

Review hackathons 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 to review

https://www.mediawiki.org/wiki/Hackathons

What to do

  1. Follow the review process Option A since this page is owned by Developer Advocacy.
  2. Complete the review checklists below.

Content review checklist

The following checklist covers both general and landing page-specific content review.

  • 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".
  • Image: If possible, include an image relevant to the topic, such as a project logo. The image can be centered or aligned opposite the title (right-aligned in LTR languages) using [[File:Example|{{dir|{{pagelang}}|left|right}}|30x30px]][2].
  • 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.
  • 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. To save space, a table of contents can be opposite the title (right-aligned in LTR languages).
  • Section headings: Section headings use sentence case. Headings should use h2, h3, and h4 styles.
  • 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.
  • Small groups: When linking to other documentation pages, a landing page should organize links into groups of no more than six.[3]
  • 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.
  • Navigation between subpages: A landing page should include a navigation element that allows readers to move between pages within the collection, such as a sidebar, navigation box, or set of tabs. If the collection is organized using subpages, include a prefix search box.
  • Lists: Do not use bulleted list items to complete an introductory sentence fragment.
  • Status: No draft or outdated banners are present.
  • 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.
  • Maintainer resources: Landing pages help facilitate the maintenance of a set of documentation. If possible, include ways for people to participate by subscribing to updates, watching pages, joining editathons, etc. Be explicit about which pages to watch to help answer questions and monitor edits.
  • Translation: If translation is available and the content of the page is stable, the page is marked for translation.
  • Mobile: The page is readable on mobile, with all important information visible.
  • Accessibility: The page complies with the accessibility guide for developers. (You can use the WAVE tool to check for critical issues.)
  • Date format: Either write out the complete date (September 1, 2021) or use YYYY-MM-DD format (2021-09-01).

Style review checklist

  • 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

This might also welcome input from a Technical Community Programs Manager (to join soon).
Current page (and its many subpages) is pretty physical-event (pre Covid) focused (and too many boxes and bold words for my taste).

Boldy CC'ing @hlepp per my previous comment

(Sorry for the Herald revert, my fault. I've disabled H379.)

hlepp changed the task status from Open to In Progress.Feb 1 2022, 5:33 PM

Basic review checklist:

  • Typos: The page has been reviewed for typos.
  • Inclusive language: The page uses non-gendered language and avoids the terms listed in the [[inclusive language]] guide.
    • Removed use of "us" and "we" to make this more inclusive
  • [n/a] Working examples: Commands and examples have been tested or reviewed for accuracy.
  • Links: Links on the page work.
    • The links all work, but they go to pages in Hackathons/Handbook that are out of date, but contain tons of good information (mixed with potentially wrong, outdated info).

I also added an intro sentence and revised headers to use active language and sentence case. This page is not marked for translation and was not translated when I made these changes.

TBurmeister claimed this task.
TBurmeister added a subscriber: mseckington.