Page MenuHomePhabricator

Improve inconsistent, long-winded, partially irrelevant, confusing [[mw:Gerrit/Tutorial]]
Closed, ResolvedPublic

Description

Been talking to GCI students on IRC who ask for help to understand parts, and everybody sharing that they get very confused. Too much noise, no clear steps plus annoying random notes inbetween that are just irrelevant, no clear structure of steps, repetitions, inconsistent language and examples, needless screenshots etc etc etc.

I've already spent a few hours on this at https://www.mediawiki.org/w/index.php?title=Gerrit/Tutorial&action=history and I'm going to spend more several hours on it and probably end up with hundreds of edits (if this was only a git repo and not a wiki, sigh), hence creating this task for transparency.

Event Timeline

Aklapper created this task.

Change 563720 had a related patch set uploaded (by Aklapper; owner: Aklapper):
[sandbox@master] Test for https://www.mediawiki.org/wiki/Gerrit/Tutorial

https://gerrit.wikimedia.org/r/563720

Aklapper closed this task as Resolved.EditedJan 14 2020, 9:40 AM

125 edits later and down from 47096 to 38209 bytes, I'm kind of okay with mw:Gerrit/Tutorial. Purrfect is the enemy of good, I guess.

  • Clarified between SSH Private key and SSH Public Key
  • Replaced "extensions/examples" repository by "sandbox". This allows people to follow the steps without creating test patches for a production repository.
  • Updated output of most commands shown as examples.
  • Removed repository specific instructions (e.g. how to clone MW core or extensions or Vagrant issues) by linking to mw:Download_from_Git instead
  • Made "Create a Wikimedia developer account" a separate step earlier in the list.
  • Replaced <pre>, <source>, <code> with {{cmd}} with proper red highlighting of variables to replace, and green for commands. Still use <code> for file names and describing commands. Explained on top that you shall not enter the $ prefix of commands.
  • Use one consistent username in instructions, instead of preilly, example, my_username, jpostlethwaite.
  • Synced @example.com and @youremail.com addresses by using only @example.com.
  • Removed editor-specific commands (vim) and distribution specific commands (apt-get).
  • Mentioned Phabricator, as the example T1234 made no sense without any such context.
  • Don't mix gerunds, imperatives, and "how to..." in section titles. Consistently use imperative.
  • Changed level of "Other common situations" and "Editing via the web-interface" so they do NOT look anymore like part of the default steps under "Submit a patch".
  • Removed numerous terminal output examples that were self-explaining. Easier to read.
  • Converted "Linux & UNIX", "Windows" and "OS X" subsections into bullet points as they bloat the ToC. Renamed "OS X" to "Mac OS X".
  • Removed numerous "alternative instructions". People need to follow one guide.
  • Removed irrelevant historic info about Git and Gerrit - there is Wikipedia for that.
  • Removed embedded videos which just duplicate text information. They are still linked under "See Also".

Potential future TODOs:

That whole section seems to be about advanced git usage, and has nothing to do with Gerrit.