Re: [docbook-apps] Producing Open Source Software

[Thomas Schraitle <tom_schr@web.de>]

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