discuss: Some of the main problems of the libre documentation
Subject:
Some of the main problems of the libre documentation
From:
Ismael Olea ####@####.####
Date:
15 Jun 2003 17:05:15 -0000
Message-Id: <1055674185.4563.88.camel@lisergia.olea.org>
El jue, 15 de 05 de 2003 a las 20:47, Togan Muftuoglu escribió:
> Well said, being able to program does not necessarily mean being able to
> document what is intended. IMHO 95% of info and man pages do suck and
> thats one of the reasons I pay X amount of dollars to publishers like
> Oreilly to get a better documentation of what I should have already by
> having the program.
This is an interesting thing. Why (some of) the Oreilly books are good?
Because the have a quality cycle of publishing.
The problem in the libre software documentation world is there are very
very few publishing professionals to teach the rest how to work with
quality levels and most of us don't know how and what to learn. If you
think about most of the programmers hate to write the problem get
bigger. And the worst thing is when some people realize about that they
start to solve the problem from scratch without interacting with
anybody. Indeed you can see how Gnome-doc, Kernel-doc, KDE-doc, TLDP,
TLDP-ES, Debian, Mozilla, OOo and so on are fighting against the same
problems: source formats, publishing formats, document registering,
quality assurance, author feedback, terminology, translation,
translation maintenance, etc.
How to solve it? We[1] believe we should get into a publishing services
outsourcer for libre documentation and libre software docs.
The idea is to concrete the publishing cycle, write an author/translator
framework and build internet services for publishing, writing,
maintaining of docs and terminology, and tutoring users. If people uses
compilers made by others to write their programs, they could use a
framework of tools and assistants to write their docs in a more easy
way.
[1] http://es.tldp.org/htmls/lucas-desarrollo.html, in Spanish.
--
A.Ismael Olea González
####@####.#### http://www.olea.org
http://aduaneros.olea.org, la ONG sin futuro.
El mundo tiene miedo a un planeta BUSH: No a la guerra.
