After pointing some people in #gnome-love to my blog entry about The Atrocities
of Gnome Developer Documentation, we had a great discussion. It
was comforting to note that others agreed with me, and some of the
particular things others said were interesting. Here are some of
those conversations (edited slightly to try to make things more clear
than the normal IRC flow).
<Misirlou> I think that the documentation for beginners should assume
that the reader knows absolutely 0% about UNIX-style
development.
<Misirlou> "Generate a patch."
<Misirlou> "Okay."
<elijah> yeah, that's how I felt too when I heard it...
<Misirlou> (Smart developer goes to RTFM on patch.)
<elijah> and then discovers that the tool they need is called 'diff'
<Misirlou> "Okay, so I need to run the diff program. Where do I run it?"
<elijah> and then wonders what order the files need to be in...
<Misirlou> "Wait, your patch was not in the right format. Also, your
indentation is all wrong."
<elijah> ah, this brings back so many memories.
<Misirlou> :(
<fer> I would like to have a _big_ developers meeting about that
<fer> most of hackers are really good, but sometimes don't take
care on social relations with newbies
<fer> so they are discouraging then
<fer> maybe the people from gnome-love should teach them just a
few things :)
<elijah> there's more to it than that...
<elijah> as I said in my blog, the documentation is nearly
impossible to wade through, making it hard for new people
to feel comfortable with their knowledge..
<elijah> so, when a new user comes along, those who were in that
position not too long ago don't feel comfortable answering
questions...
<sri_> indeed
<sri_> the quality of our docs suck
<elijah> so instead, they point the newbies to the docs...
<fer> to the wrong docs
<elijah> and the newbies feel like they received a "fend for
yourself" response.
<elijah> fer: yup
<sri_> yeah :(
<sri_> and what you get is only a subset of people who are willing
to slog through the docs and the source.
[Editorial note: also, those who probably could answer the
question are busy hacking and thus aren't available to answer the
question; which is why those who are less certain of themselves
try to offer a guide they are aware of, but the newbie definitely
doesn't know that.]