Re: [gnome-love] GNOME Hackers Kickstart Guide 1.0 Released

[Elijah Newren <newren gmail com>]

On Sat, 12 Mar 2005 14:18:03 -0500, Luis Villa <luis villa gmail com> wrote:
> Cool! I've linked to this and Elijah's similar doc at:
> http://live.gnome.org/DocumentationProject
>
> Madan, did you or others look at Elijah's document when you were
> working on yours? Are they complementary, or is there overlap? If
> there is overlap, maybe both could be moved to the GNOME wiki and
> merged there?

I took a little time to look over the this kickstart guide.  It is
really cool.  They do have information that my guide doesn't have,
though they also have lots of overlap too (despite actually
referencing my guide and pointing people to it as one of the
steps...?).  However, I am _really_ opinionated and don't think
merging makes sense in this case[1] and I am totally against putting
my guide in a wiki[2].  I think what we have is two guides that are
meant to cater to significantly different audiences.

Cheers,
Elijah

[1] I think that the kickstart guide, while cool, has a totally
different audience than my guide.  Here's issues that I think make
their guide totally different and incompatible, as well as some
nit-picks about problems with the guide in general (keep in mind that
I could produce a pretty long list of problems with my guide too, so
I'm not trying to be mean or anything): (1) They spend time on
choosing a distro and connecting to the internet (and they suggest
apps like Qinternet and Kppp!?!), (2) they start introducing basic
linux commands such as mv and rm--without examples; I did some
introduction of commands too (with examples) but not at quite the same
level--perhaps the more basic commands like mv and rm would be useful
to cover but in a separate guide, (3) they wait until "level 3" (kind
of like "chapter 3") to explain what Gnome is in their "Gnome Hackers
Quickstart guide" ;-), (4) they want everyone to create a bugzilla
account before looking at or explaining any code, (5) They suggest
manually settings paths and environment variables instead of letting
jhbuild do the work for you (too confusing--I had to explain how this
wasn't needed to at least one person in #gnome-love already), (6) they
cover what bugs and enhancements are and how to submit them to
bugzilla--before getting into anything about coding, (7) they link to
dozens and dozens of general references on development, some of which
are *very* out-of-date, before covering anything about coding, (8)
When they get to where they start covering coding at the very end of
the tutorial, the start with "Every Gnome beginner should understand
the basics of the Gnome project by reading Getting Started." and link
to http://developer.gnome.org/documents/joining-gnome/gettingstarted.html
-- that page is so out-of-date that it does far more harm than good; I
convinced Murray to just flat remove it from the 2.10 release notes
without a replacement due to identifying over 12 severe problems with
it.

[2] I think putting beginner documentation in a wiki results in all
the problems I described at
http://www.gnome.org/~newren/tutorials/developing-with-gnome/html/ch01.html#dontlearn
taking over the guide.  I've seen it happen; wiki documentation can be
great for the intermediate to advanced user but I think it sucks for
writing beginner documentation.