Page MenuHomePhabricator

[[mw:Gerrit/Tutorial]] is way too much information for new contributors
Closed, ResolvedPublic

Description

As Rachel, Srishti and I discussed this yesterday:

Looking at https://www.mediawiki.org/w/index.php?title=Gerrit/Tutorial&oldid=2414566 I am wondering as usual if we could have a way shorter How-To / move more content into subpages.
Compare its epic length to e.g. https://wiki.documentfoundation.org/Development/gerrit and https://wiki.documentfoundation.org/Development/GitReview and https://wiki.documentfoundation.org/Development/gerrit/FAQ and https://wiki.documentfoundation.org/Development/gerrit/SubmitPatch

This would mean rewriting existing pages, not adding even more pages to the mix.

This task is a followup to T134256: Make Wikimedia's Git/Gerrit documentation less horrible and less scattered.

Event Timeline

Aklapper created this task.Mar 31 2017, 3:40 PM
Aklapper updated the task description. (Show Details)Mar 31 2017, 3:43 PM
Aklapper updated the task description. (Show Details)
Aklapper updated the task description. (Show Details)Mar 31 2017, 3:47 PM
Qgil triaged this task as Low priority.Sep 12 2017, 8:29 AM

Let me insist. :)

This is what I used when I set up my own developer environment as a total newbie. If I would have a doubt or get stuck ion anything, then I would go to the basically exhaustive tutorial or whatever related page with more information.

Let's see if our new survey will detect a specific problem with these two pages.

Indeed, https://www.mediawiki.org/wiki/Gerrit/Getting_started looks like a great how-to.
One thing left to decide/sync: Gerrit/Getting_started says git review. Gerrit/Tutorial says git review -R (to not rebase).

I think we should include both the manual way and git-review. Since many users are finding using http clones with git review does not work. If it specified the manual command we can direct users to use that :).

What is "the manual way"? Please be clear and provide specific commands to make sure we talk about the same things.
How-tos are supposed to provide exactly one single way. Tutorials might explain reasons for certain things and might also mention additional options.
However, for issues with http clones, that's what Troubleshooting is for.

Manual command I mean is something like git push, git pull.

Aklapper lowered the priority of this task from Low to Lowest.Jan 2 2018, 3:34 PM
Aklapper raised the priority of this task from Lowest to Low.
Aklapper moved this task from To triage to Jan-Mar-2018 on the Developer-Advocacy board.
Aklapper closed this task as Resolved.Jan 2 2018, 11:03 PM

https://www.mediawiki.org/w/index.php?title=Gerrit/Tutorial&oldid=2677976 and https://www.mediawiki.org/w/index.php?title=Gerrit/Getting_started&oldid=2677975 now explain in the very first line that one is a tutorial (learning oriented, with explanations to allow a newcomer to get started) while the other is a how-to guide (goal oriented, series of steps to solve a specific problem).
Those are definitions taken from https://www.divio.com/en/blog/documentation/

Looking at https://www.mediawiki.org/w/index.php?title=Special:WhatLinksHere/Gerrit/Getting_started&limit=500 and https://www.mediawiki.org/w/index.php?title=Special:WhatLinksHere/Gerrit/Tutorial&limit=500 I don't see strong reasons to change any links on pages to link to 'the other page'.

Hence closing as resolved.

Qgil awarded a token.Jan 3 2018, 2:40 PM
Dvorapa added a subscriber: Dvorapa.EditedApr 9 2018, 4:35 PM

Hi, I just want to announce I proposed Getting started page to rename as its purpose is slightly different than its name (as worked on in this task). See https://www.mediawiki.org/wiki/Talk:Gerrit/Getting_started for further information

Hi, I just want to announce I proposed Getting started page to rename as its purpose is slightly different than its name

@Dvorapa: Indeed. I'd love to follow the categories on https://www.divio.com/en/blog/documentation/ closer (Tutorials, How-to guides, Reference, Explanation).

Dvorapa added a comment.EditedMay 2 2018, 5:34 PM

! In T161901#4175041, @Aklapper wrote:
I'd love to follow the categories on https://www.divio.com/en/blog/documentation/ closer (Tutorials, How-to guides, Reference, Explanation).

Wow, this page is really excellent!