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

[Deb Richardson <deb@linuxcare.com>]

(Note: this is going to be my last crossposted message.  I'll be posting
all followups only to ode-discuss@oswg.org.  Archives will be available
if anyone misses anything.)

Aaron Turner wrote:

> Personally I would be very interested in getting the Free/Open/NetBSD and
> other groups involved in such a project.  I however also feel (rather
> strongly) that content should be compartimentalized so that when I'm
> looking for getting Apache to run on Linux I don't keep running into
> FreeBSD centeric docs.  Of course these compartments can overlap, but we
> need to be able to split it up for the end user.

This is where things get complicated.  Who should document Apache, for
example?  The Apache Group?  The LDP for Linux?  The FreeBSD for
FreeBSD?  Etc.  Logically, of course, Apache should be documented by the
Apache group.  Additional documentation can be written to further
enhance existing docs -- enhancements by the LDP for Linux, by the
FreeBSD folks for their OS, etc.  There could even be separate
expansions written for each separate Linux distribution -- "Apache on
Red Hat", "Apache on Debian", etc.

Should all of these documents be stored in the same place and maintained
by the same group?  No.  Apache docs belong with the Apache projects,
LDP docs with the LDP, and so on.  

On the other hand, a centralized "card catalog" like that the Open
Source Research Team (OSRT) is working to develop, should and could
effectively index and cross reference all of these documents.  The docs
aren't in the same location, nor are they controlled or updated by the
same group.  Instead, all documentation projects are working together
with the OSRT to develop and maintain the meta-information that goes
into the card catalog.  I really like where the OSRT is going with this,
and am very interested in working with them to make it a reality.

The docs will already be individuated by OS, package, etc., simply by
belonging to different projects and existing on different sites.  What
the OSRT card catalog promises is the ability to quickly and easily find
the information you need through a centralized repository of
meta-information that is cooperatively maintained by all these different
projects.  Simple is better.  The OSRT is working on a simple but very
powerful solution.

> Wouldn't using the LSB or LDP exclude the FreeBSD'ers as those are Linux
> specific organization?  I'm confused about the relationships between the
> various groups as you propose.

I specifically said that the LSB should be treated as the standards base
for Linux.  I didn't suggest that it be used for/by other projects.  If
the FreeBSD folks want to use the same standards, they can.  If they
don't, they don't have to.  If there were only one Linux-related
documentation project, then that documentation project would be the
logical place to develop and promote Linux documentation standards.  But
there are multiple Linux-related documentation projects, just as there
are multiple distributions, etc.  Similarly, if there were only one
Linux distribution, there would be no need for an LSB. 

As far as I know, there is only one FreeBSD-related documentation
project.  (I could be wrong about this, and folks should correct me if
I'm in error).  As such, the FreeBSD DP is the logical organization for
developing documentation standards for FreeBSD.  

Now, if we have open lines of communication between the various
standards-developing organizations (ie: The LSB, the FreeBSD DP, the
GNOME DP, etc), then these organizations can discuss chosen or proposed
standards as a group.  But we don't need another organization to do
this...we don't need another committee.  All we need is a mailing list
that interested people can participate in.  Simple is better.  

> As long as you have an open standard, others can write tools for it.  HTML
> is such an example.

HTML is "sort of" a standard.  It's also an output format, being used
primarily to mark up the formatting and appearance of a document.  It is
not appropriate as a source format for documentation.  SGML, on the
other hand, allows documents to be marked up for structure and content,
rather than for formatting.  Formatting is done later, when the document
source is processed to produce the various output formats.  SGML also
allows for far more verbose markup, meaning that there is more that can
be done with the structural information during processing.

DocBook is the best SGML DTD available for the creation of structurally
marked up documentation source.

> For me at least, I've always been interested in a system where the content
> and retrevial engine are very integrated.  It still can and should be
> open, but such a system has many benifits for the end user.  Realize that
> I'm not talking about so much about the markup of the document, but rather
> the storage and retrieval of the document itself.

Hm.  Could you explain this a bit more?  I think I know what you're
getting at, but I want to make sure before I comment.
 
> I would assume though that it would be quite
> possible for someone to develop a web form or the like that the writer can
> fill out to create a DocBook compliant article for the small stuff.

It's possible, but would be unnecessarily complicated.  DocBook allows
you to mark up far more than just "author", "title" and "paragraph". 
You can mark up filenames, directory names, screenshots and details,
tables, tables of contents, index words, lists, commands, command-lines,
command-line options, replaceable values, environment variables...and so
on and so on.

Creating a web-based editor for even the simplest of DocBook documents
would be significantly complicated.  Also, many people (myself included)
don't care for web-based editing tools (it's my biggest gripe with Zope,
actually).  Finally, there are a number of editing tools already
available that are being improved to better support DocBook, including
psgml (emacs), and LyX.  Again, simple is better, and in this case it
would be unnecessary to reinvent the wheel.

Mozilla is going to offer some very interesting possibilities for the
creation of an editor and processing tools, as well.  Mozilla is far
more than just a web browser.

> I've seen situations where the author chose not to pick a good license and
> it ended up causing a lot of problems.  

Unfortunately, that's simply part of the game.  Sometimes people will
choose bad licenses.  And they are (and must remain) free to do so. 
This whole thing is about freedom.  We cannot lose sight of that.

> Also lack of standardized licenses prevents a centralized repository which
> is desperately needed.  You can't expect end users to look at 20 different
> sites looking for one answer just because some dufus couldn't pick a good
> license.

We don't need a centralized repository, we need a centralized index. 
The Open Source Research Team is making very exciting progress in this
area with their meta-information project.
 
> I guess I don't know how to do the standardization required to pull this
> off without creating a dedicated oversight committee to manage it.

It's simply a matter of scope.  We do not need a centralized
repository.  We do not need to standardize licenses.  What we need to do
is discuss the possibility of cooperatively developing a set of open
standards for Open Source documentation.  Within Linux, that can be the
LSB.  Within the Open Source community as a whole, all we need is a
mailing list on which a sufficient number of different projects will
actively discuss these issues.

Another committee is unnecessary, and would only serve to further
complicate the situation, both practically and politically.

> That's one reason why I'm against a distributed system.  You can build
> such a system in a monolithic manner.  Making it distributed is
> significantly more complicated.  

Not really.  Open Source documentation already exists in a distributed
system.  All we need to do is develop a centralized index so people can
easily find the information they're looking for.  The OSRT
(http://www.metalab.unc.edu/osrt) has already made significant progress
towards making this a reality.

> It's already unmanageable- do a search on Yahoo for some linux related
> question- "Linux pop3 server" returns 13,000+ hits.

Thus the need for the OSRT's card catalog.  It's more than just a search
engine.  Their meta-information project promises to create a
comprehensive and extremely powerful resource for open source
documentation.  As Paul mentioned, they're politically and
technologically neutral, and they're working with open standards to
produce some remarkable tools.

Really, you should go check it out :)

(Paul, maybe you could give us a rundown about the project?  I'd also be
interested in knowing how the meta-info project is progressing and if
there's any way we (that's a rather general "we") can help).

- 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.


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org