More comments on developer documentation atrocities

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

Comments are closed.