Hi,
On Mittwoch, 4. March 2009 22:18:57 Stefan Seefeld wrote:
> > Although the above statement contains some truth, open source
> > projects fail because of something different: the lack of
> > documentation. :)
>
> This statement is just as wrong (since over-simplistic) as the above,
> I'm afraid. But I do agree about the importance of documentation.
Well, yes, the statement was over-simplistic although it was not meant to
be aggressive or insulting. :) Maybe the wording was a bit unfortunate.
It was more meant as an example of one piece of the overall picture. As
my focus is more on documentation, I just concentrated on this piece. :)
I have an example, maybe that makes my statement a bit clearer:
Perhaps my "over-simplistic statement" was also influenced when I tried
to work with the Python bindings for Subversion. Maybe the situation has
changed now, I haven't looked again. Some time ago it was just an
example of great nothingness: No quickstarts, no examples, no
documentation, nothing. I really wanted to use them and I tried to find
examples, but in the end I gave up. So in that sense, this project
has "failed" for me.
Of course, I don't believe, this is true for all projects! It depends on
the nature of the project. There are projects that can live without any
documentation as they are self-explanatory.
But for more complicated projects, in my opinion this little example
shows one thing: either you are willing to spend some time and effort
and derive all your conclusions from the source code or from trying it
out, OR you look for something else with equivalent features. What do
you think other developers do? Would they spend their time on a
research-and-development-journey?
IMHO Subversion is a good counter-example: the developers understood the
importance and value of documentation. They've created this well-written
piece and whenever people have problems, they can look into the HTML page
or the PDF file.
> > [...]
> > From my impressions with developers, they tend to underestimate the
> > importance of documentation. Of course, there "natural" thinking is
> > "Why should I 'document' my things? Why should I care? Read the
> > code, it's there!"
>
> I would phrase it a little differently: When you stare long enough at
> a problem, it becomes obvious to the point where you can't see
> anything worth documenting. It's all clear (to you).
Well, maybe that could be the case. But a developer who works on
complicated things, maintains a blog and can not write something of his
own work? Let's face it: Writing is not as sexy as coding, as simple as
that. ;-) And believe me, I know both sides. :-)
> I'm not sure what can be done to get over this mentality. This is
> certainly not a technical problem, but a cultural one.
Depends. I made the experience, that developers underestimate the
importance of documentation. This is "natural" because they are
developers and not writers. In that case, you can say, this is a
cultural problem.
On the other side, there is also the technical aspect. Developers who
*want* write documentation face lots of methods, and DocBook is just
one. Although DocBook might be superiour over other methods, most
developers that I've met find it "too difficult"---for whatever reason.
Tom
