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