On Thu, 2015-03-19 at 09:54 -0400, Michael Hill wrote: > On Thu, Mar 19, 2015 at 9:11 AM, Michael Catanzaro > <[email protected]> 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 _______________________________________________ gnome-doc-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/gnome-doc-list
