About the Standard Documentation Proposal

[Ismael Olea]

(This letter can be found in the web at
http://olea.org/columnas/2004-02-13-standard_documentation_proposal.html)

Recently I've found the discussion about a document standard proposal
which really interested me. For many years I've been thinking how to
solve the problem of maintaining e-libraries, specially about libre
software.

I've tried to follow the archived discussion and I'd like to comment
some things in order of trying to help with my experience in this
fields.

First of all, I think we need the most general solution we can afford.
Web libraries as TLDP.org or ES.TLDP.org share almost exactly the same
problem as the personal document management on a desktop or in a
multiuser server.

Other point, IMHO, is the unquestionable need of using XML/W3C
technologies as our data base. I'd thought nobody would prefer other
alternatives but found that .desktop proposal and, sincerely, seems to
me it don't fit in the web view neither the system wide use. Having an
XML data system we can be sure we are ready to the next future whatever
it'll be.

And between the idea of choosing a pure XML or RDF alternative, I think
the first one is more recommendable. We can express our meta-data on
XML, which is very well supported in almost all present development
platforms and well have the same use of both technologies at least at
the first steps. Also, XML can be used in namespaces and, in the future,
RDF could be used to relate to other metadata XML schemas or other new
applications. BTW, I remember the times of the considering in the OMF
working group about choosing XML or RDF, then, Paul Kendall wrote an
analysis about why XML is preferred. Sadly I think the server which
hosted the email list is dead now.

About the ScrollKeeper approach, I'm really happy with it, at least in
the wide perspective. It seems to me to be very elegant and flexible and
adaptable to the system-wide and distributed web use. For example you
can use it to add _all_ the documentation in a present linux system into
a comprehensive documentation manager. This is absolutely _great_ for
compatibility with legacy systems (like the ancient man and info
systems). The fail of a more wide use of it I think is in the
distribution packagers, who could use the ScrollKeeper services no
matter the application is, in the same way you can express in a RPM file
what files are documentation using an special instruction.

I think ScrollKeeper can be used even for registering remote documents
into the local doc management system, which is very suggesting for me.

About the problem that developers had had creating OMF.xml files, it is
obvious for me a set of tools is needed to help in the creation and
maintenance of them. That tools will work as an automated QA control.
And I have the opinion that documentation and software publishing has
lots of similarities, so, as you can suppose, a set of "auto-tools" for
documentation are needed to, specially if you try to propose the use of
conventions/restrictions in the creation and managing of documentation
in order to have an almost 100% automatic management, with QA control
and flexibility.

A very interesting thing for me these days is the need of a controlled
vocabulary in the metadata info for the categorization of documents,
since it'll let the automated publishing without any assistance. The use
of Freedesktop previous standards seems to be very suggesting but I
think it needs consider adding/merging with other points of view, for
example re-using the years experience collected in *.TLDP.org. This
brings me to one of my conclusions about the need of specifying a
"publishing policy" standardized for libre software documentation, which
could help documentation writers to focus on well defined types of
documents. This brings to me too to the need of have an strong revision
of the OMF spec. At this moment I don't have a ended proposal but I'll
love to help with the present ideas I'm working on.

Finally I want to say that I'm very happy this effort is happening. Me
myself was thinking some time ago about starting a similar one and
considering to do it at Freedesktop.org. I think this is the momment and
we are the people to do it. I hope I can know how to help in this
beautiful work.

PD: Next week TLDP-ES is organizing a workshop and a meeting about our
advances at the Open Source World Conference. If some of you plans to be
there will be a pleasure talk in person about all of this. Happy hacking
:-)


-- 
        A.Ismael Olea González

        mailto:ismael at olea.org  http://www.olea.org
        http://aduaneros.olea.org, la ONG sin futuro.

        El mundo debe empezar a tener miedo a un planeta OLEA
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.freedesktop.org/archives/xdg/attachments/20040314/08041384/attachment.htm