Re: [oswg-dis] Re: Open Document Environment (ODE)

[Deb Richardson <deb linuxcare com>]

There are a number of problems with the ODE proposal that I believe are
likely to be insurmountable.  I could be wrong, but I'll outline them
here so we can discuss them.

To be honest, I am unconvinced that creating an "umbrella group" such as
this is necessary, or even that it's a good idea.  Open Source and
related projects work because they tend to not be monolithic, their
infrastructures are usually simple and make use of well-known
technologies, and there is little implication of there being a heirarchy
of people and projects.

On the other hand, I do feel that developing a set of standards for Open
Source and Open Content documentation could be extremely useful.  Having
a commonly used set of standards would be very powerful.  But creating a
new organization for the development and maintenence of these standards
is much more complicated (both practically and politically) than folks
might suspect.

If we are going to work towards the development of a set of standards
for Linux documentation (which seems to be the gist of the discussion so
far -- the FreeBSD and other folks are being left out at this point), I
think we should develop these standards in cooperation with an existing
group, such as the Linux Standard Base.

The LSB website can be found at http://www.linuxbase.org.

The LSB is an orgazation working to develop and promote a set of
standards that will increase compatibility among Linux distributions
that will enable software applications to install and run on any
compliant Linux system.  The LSB is already being supported by a large
number of companies and organizations, including Linuxcare, Corel, the
Debian Project, TurboLinux, VA Linux, SGI, Software in the Public
Interest, Red Hat, and more.

Are documentation standards within the current scope of the LSB?  Not
that I know of.  But I cannot imagine that the LSB would be unwilling to
examine a proposal and work with us to develop and promote whatever
standards we devise.

As for the development of standardized tools -- well, this is definitely
outside the scope of the LSB.  It is also a very non-open-source idea --
one of the beautiful things about Open Source is that it provides a user
with choice -- a choice of distributions, of packages, of licenses, of
programs, etc.

We don't need a standardized tools if we have an open documentation
standard that is supported and promoted by the majority of Open
Source/Linux documentation projects.  One standard, used as the basis of
even hundreds of different tools, is good enough.  As long as the tools
are compliant with the standard, that is.  People will be able to choose
from among these tools to find those which best suit their own needs,
systems, and work preferences.

The idea of a "bookshelf" is a bit shortsighted.  The majority of Open
Source docs are delivered and used in electronic formats.  The whole
idea of a "book" is somewhat antiquated in the face of these electronic
formats.  Also, if you look around, the Open Source documentation
community (the volunteer writers, editors, etc) have produced few large
works.  Most of the documents we have are short -- HOWTOs, MiniHOWTOs,
FAQs, etc.  There's a reason for this -- writing documentation is hard.
Writing short, focused, procedural-style documents is simply easier than
writing a book.  It takes a great deal of time, dedication, and bloody
hard work to produce a book.  You're going to find precious few people
who are going to volunteer their time to do so.

So, why not have a bunch of volunteers collaborate on a single
monolithic work?  It's more likely that such a project would be
successful, but there's still a lot of work that goes into developing,
coordinating, and maintaining such a project.  And the result is still a
"book" which, as I've mentioned, is a bit limited given the power and
flexibility of electronic formats.

I do _strongly_ support the idea of using DocBook as a document format
standard.  Aaron mentioned that having to do short docs using DocBook
would be a bit of a pain.  That's true.  Using DocBook to markup long
docs is a bit of a pain, to be honest.  But the results are worth the
effort.  SGML is a very very powerful tool.  Used properly it can make
cross-referencing, indexing, and other stuff happen as if by magic.  I
cannot express strongly enough my belief that we should support and
promote DocBook as an open source documentation standard.  It's a
standard within itself, as well, meaning that it can be used universally
without any one documentation project being able to control or
monopolize its development.  The number of documentation projects that
are using DocBook is growing, and currently include KDE, GNOME, the
OSWG, the LDP (partially), FreeBSD DP, and more.  DocBook has begun to
establish itself as a defacto standard already, simply because it is the
most appropriate and powerful tool for the job at hand.

The docbook site is at http://www.docbook.org

Licenses.  Licenses should _not_ be standardardized, nor should be
attempt to do so.  Each project and each author should be given the
freedom to choose whatever license best suits his/her/their needs,
within the scope of the project they are working on.

This also means that we should not and cannot really insist that all
open source documentation be enveloped into a single centralized
repository.  Having different licenses makes this unrealistic and very
complicated.  And the sheer effort that would be required for developing
and maintaining such an infrastructure is immeasurable.

> 4) Creating a new umbrella group is good.

I don't agree with this at all.  An umbrella group implies that one
group is superior in a hierarchy to other groups.  Developing open lines
of communication and cooperation between documentation projects is
good.  Creating "yet another committee" is bad.

I am interested in discussing the future of Open Source and Open Content
documentation with all related projects.  I think that these groups (and
others...we should really be communicating with the FreeBSD DP and other
groups about all of this) could have some incredibly interesting and
enlightening discussions about these issues and more.  That's why I
created the Open Source Writers Group in the first place -- as a channel
of communication between documentation projects.

> 5) Keeping a Linux slant on things IMHO is a good thing.

Keeping a Linux slant on things IMHO is a bad thing.  Encouraging the
development of open documentation standards through cooperation with and
promotion of the LSB is a good thing for Linux.  Developing and open
standard for the creation of meta-information (through supporting and
promotion the Open Source Research Team (OSRT)) is a good thing.
Supporting DocBook as an open documentation standard is a good thing.
We need to work on developing standards that everyone can work with.
Ideally these standards would be supported and developed in cooperation
with as many OS/OC documentation projects as possible.  For Linux, these
standards should be developed in cooperation with the LSB.

The OSRT website can be found at http://www.metalab.unc.edu/osrt/

The rest of the ODE proposal -- involving the development of a
centralized monolithic infrastructure is, in my opinion, simply
unrealistic.  We can achieve a great deal of good through supporting
open standards and through promoting and supporting the meta-information
work that the OSRT is working on.  We simply cannot expect such a huge
and unweildy project to ever a) be completed, and b) work.  It's just
too much to expect volunteers to undertake, and it's really not a good
idea.  Massively complex infrastructures simply have too many possible
points of failure.  I would be surprised (very) if such an
infrastructure could be completed, nevermind used.

What the open source documentation community really needs isn't more
infrastrucutre or committees at this point -- what it needs, quite
simply, is more people sitting down to write documentation.  We have to
first figure out how to get more volunteers to create more content.
When the quantity of available documentation begins to outstrip our
ability to effectively manage that documentation, _then_ maybe we'll
need to start thinking about developing more complex and scalable
infrastructures to handle it.  Right now, the number of open content
documents is rather pitifully small, and the quality of those documents
wanders the full range from "practically unreadable" to "brilliant".

We need to support open standards, including a standard method for
creating meta-information.  We need to figure out how to get more people
writing content.  We need to figure out how to improve the quality of
the content produced.  Etc.

We have a whole host of more pressing problems that need first to be
addressed.

All that said, I would very much like to discuss how people think that
the various open source documentation projects can work together.
Again, as I mentioned once before, I created the OSWG to encourage this
sort of inter-project discussion, because I do think that we can learn a
great deal from one another and work together in very valuable ways.

- deb


-- 
Deb Richardson, Executive Editor
Linuxcare, Inc.
tel: 613.562.9723, fax: 613.562.9304
deb@linuxcare.com, http://www.linuxcare.com

Linuxcare.  At the Centre of Linux.