Page MenuHomePhabricator

Review contributing landing page (New Developers)
Closed, ResolvedPublic

Description

See also: T274236: Have a process to regularly review projects listed on mw:New_Developers, maybe T252147: Improve the new contributor onboarding process

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://www.mediawiki.org/wiki/New_Developers

Notes

Should be updated to include links to wikicontribs and content from https://www.mediawiki.org/wiki/Developer_account. Look into added programming language based browsing

Content outline

  • Welcome!
  • "How to get started contributing": 4-step process
  • "Basics of how Wikimedia software projects work ": Overview of open-source project components (task tracking, code repo, code review, discussion)
  • "Choose a software project" (huggle, kiwix, commons app, wiki ed dashboard, library card, pywikibot) - project list to be updated by Developer Advocates in advance of May 2022 Hackathon.
  • Other ways to find projects: Outreach programs & good first tasks
  • Additional resources
  • “General communication tips” (This section is also translcuded on How to be a MediaWiki hacker)

Basic review

  • 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.
  • [n/a] Working examples: Commands and examples have been tested or reviewed for accuracy.
  • Links: Links on the page work.

Writing style review

  • 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.
  • 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").

Details

Due Date
May 7 2022, 3:59 AM

Event Timeline

TBurmeister changed the task status from Open to In Progress.Mar 7 2022, 3:04 PM
TBurmeister claimed this task.
TBurmeister triaged this task as Medium priority.
TBurmeister changed the task status from In Progress to Open.Mar 7 2022, 7:53 PM
TBurmeister removed TBurmeister as the assignee of this task.
TBurmeister added a subscriber: TBurmeister.
Aklapper renamed this task from Review contributing landing page to Review contributing landing page (New Developers).Apr 15 2022, 6:53 AM
Aklapper updated the task description. (Show Details)

https://phabricator.wikimedia.org/T169599 Has additional thoughts that I think are relevant and helpful for updating this page and understanding the history of our attempts around this topic

Completed updates to improve and simplify the text in all sections except:

A hefty revision of the communication tips template (which is transcluded in "How to become a MediaWiki hacker") is here:
https://www.mediawiki.org/wiki/User:TBurmeister_(WMF)/Sandbox/Communication_tips

I'd love any feedback before I make this update.

LGTM! I made some small edits. Thanks!

https://www.mediawiki.org/wiki/New_Developers/Communication_tips is updated.

Given the scope of my changes, I removed all existing translate tags from this page because I think it should just be translated as if it were a new page. There's some phrases here and there that are the same, but so much of the wording, and all of the structure, is new. If removing all the translate markup is NOT the way to get this page re-translated anew, please LMK a better way to proceed. Thanks and apologies for being perhaps too bold.

Makes sense. Breaking up/fiddling with lotsa strings and easy-to-break markup is way too cumbersome with our <translate> markup so that's the tradeoff, I'm afraid.

Going to mark this as Resolved because all the content has been improved as much as it can for the scope of this doc task; the larger issue of updating and maintaining a good list of first tasks or projects for new contributors is tracked in other tasks like T274236,