[Doc-SIG] Editorial for freshmeat

[Manuel Gutierrez Algaba]

The need of documentation. Open Source phase II

As more and more programms are made and as more and more
information is available in USENET, free electronic books, 
tutorials, and so on, the bigger the problems to use/handle
that information/code
are. 

The main advantage of Open Source stuff: 
- Use and reuse of information/code (freely)
should be or could be greatly improved using wise
(marking) documentation.

Almost nearly every programm ( even the simplest one) is 
divided into several parts, each part is related to something
very specific (usually) :
- sockets
- GUI 
- formatting into html/TeX
- i18n
....

So every programm does a 'main' task by resolving many other
small common tasks. 

The developer of programms who learns by reading other's code
knows how to find those common tasks. Well, sometimes. Firstly,
because the code is not always well structured enough. Secondly
because he lacks the time , patience to browse in the middle of
so much code. 

The user sometimes has a very hard time trying to setup, identify
the components of the programm or simply learn how to use it. This
is mainly because of a 'monolithic' info. I'll argue against this
"man-page-hacker-like" attitude later. 

So we have a Open Source programm that can't be fully reused/used
by the lack of information or by a deficient structuration. 
This is very, very common and it'll become more painfully common
in the future. 

Most developers are happy enough when their code runs smoothly (or
simply runs), when they've managed to arrange the code so it 
compiles and does something. In fact, most developers struggle
non stop with buggy code, adding new features and so on, they
pay little attention to the fact that most of the C/python/perl/java 
modules solve relatively "general" problems (KDE programming,
sockets, i18n, special formatting). Of course, if they're good
enough they'll put most of it into libraries and objects, but then
 those libraries and objects will remain "hidden" behind the 
"main tasks" of the programm. I wonder:
If you spend three days solving small problems, why don't you 
spend ten minutes marking those solved small problems (GUI, i18n...)
somehow.

This way your programm would be useful twice: by itself, by the
objects and libraries it keeps. 

Is this marking difficult? How can I do this marking?

One answer is using XML, sgml or something like that. 

[ MUCH MORE TO BE SAID STILL]

Is this subject/style appropiated ? Is it worth that I finish
this article to be published ? It's unfinished because I'd like
the assurance of it's worth the effort.

I'm the author of some free programms(some in freshmeat),
 see URL above.

Regards/Saludos
Manolo
www.ctv.es/USERS/irmina    /TeEncontreX.html   /texpython.htm
 /SantisimaInquisicion/index.html 

  Man's reach must exceed his grasp, for why else the heavens?