Re: Proposal to make GnomeLove official and move it to developer.gnome.org

[Michael Catanzaro <mcatanzaro gnome org>]

On Thu, 2015-03-19 at 09:54 -0400, Michael Hill wrote:
> On Thu, Mar 19, 2015 at 9:11 AM, Michael Catanzaro
> <mcatanzaro gnome org> wrote:
>
>         Having multiple conflicting tutorials is confusing to new
>         contributors,
>         and harmful when those two tutorials are incompatible.
>
>
> Disclaimer: I am not a jhbuild beginner. 
>
>
> Please find an example other than jhbuild for harmful incompatible
> tutorials.

I'm really thinking of jhbuild specifically here. I don't think this is
a more general issue for us.

>  Regardless of other documentation that existed when the HowDoI was
> created, it is actively updated as jhbuild changes by Ryan, a
> developer and contributor to jhbuild. It has proven ideal in a
> hackfest environment for all levels of user (although an intern at a
> hackfest can't be classified as a beginner either).

What advantages do you see in this page over GnomeLove/BuildGnome?

> It's where I look to see what has changed with jhbuild since the last
> time I ran it, and is arguably the best source of information for
> other tutorials whose goal is to *not* conflict.

Well, where it instructs users to undo changes recommended by
GnomeLove/Jhbuild, specifically putting ~/.local/bin into $PATH, that is
very problematic. I don't see any harm in modifying $PATH, but if that's
really so bad then we should modify the advise of GnomeLove/Jhbuild
instead of advising in a completely separate tutorial not to follow the
instructions in the other tutorial....

> It regularly achieves legitimacy by being replicated on
> developer.gnome.org, where it's cleverly concealed from beginners
> performing case-sensitive searches. It brings the perspective of
> multiple platforms.

The thing is, looking through it I really don't see anything important
that's not already covered by GnomeLove/BuildGnome. There is more detail
on everything, and a bit of that we could merge into
GnomeLove/BuildGnome, but GnomeLove/BuildGnome has all of the necessary
information for newcomers in a shorter, easier format.

I think the main thing missing from GnomeLove/BuildGnome is a big
warning not to use --nodeps or 'jhbuild buildone' before 'jhbuild
build'... it's incredible how many helpless users we have on IRC who
don't realize that you need to build dependencies.

If we don't want to redirect from HowDoI/Jhbuild to
GnomeLove/BuildGnome, then I'd like to see it prominently link to
GnomeLove/BuildGnome at the top of the page, directing new users to that
guide instead. And preferably also undergo a reorganization so that it's
no longer in tutorial format. We shouldn't have two different tutorials.
Another option would be to give up on the short, easy format if most of
us like HowDoI/Jhbuild better, and redirect from GnomeLove/Jhbuild to
HowDoI/Jhbuild. That would still be much better than having two
different tutorials.

Michael