Page MenuHomePhabricator
Create Task
Maniphest T161901

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

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.

Related Objects
Search...

Event Timeline

Aklapper created this task.Mar 31 2017, 3:40 PM
Paladox subscribed.Mar 31 2017, 3:42 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 subscribed.Apr 20 2017, 8:19 AM

Is https://www.mediawiki.org/wiki/Gerrit/Getting_started too short?

Qgil added a project: Gerrit.Apr 20 2017, 8:20 AM
Paladox moved this task from Bugs & stuff to Discussions & doc stuff on the Gerrit board.Apr 26 2017, 3:12 PM
Aklapper added a parent task: T169599: Sort out concept for overview/entrance pages targeting our developer audience.Jul 20 2017, 3:21 PM
Qgil triaged this task as Low priority.Sep 12 2017, 8:29 AM

Let me insist. :)

In T161901#3196709, @Qgil wrote:

Is https://www.mediawiki.org/wiki/Gerrit/Getting_started too short?

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.

Aklapper claimed this task.Oct 19 2017, 10:59 AM

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

Paladox added a comment.Oct 19 2017, 11:23 AM

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 :).

Aklapper added a comment.Oct 19 2017, 11:34 AM

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.

Paladox added a comment.Oct 19 2017, 11:43 AM

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 edited projects, added Developer-Advocacy (Jan-Mar-2018); removed Developer-Advocacy.
Aklapper moved this task from Backlog to January on the Developer-Advocacy (Jan-Mar-2018) board.Jan 2 2018, 10:59 PM
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 subscribed.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

Aklapper added a comment.May 2 2018, 2:46 PM
In T161901#4117509, @Dvorapa wrote:

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!

hashar moved this task from Discussions & doc stuff to Bugs & stuff on the Gerrit board.Mar 1 2023, 10:55 AM
Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct. · Wikimedia Foundation · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL · Credits