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

[Aaron Turner <aturner linuxkb org>]

On Sun, 9 Jan 2000, Deb Richardson wrote:

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

I don't think anyone is suggesting we write new standards when there
already are standards for documentation markup such as Docbook and
Linuxdoc.  I for one would be against developing yet another documentation
standard to compete for people's writing efforts.

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

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

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

I would assume so as well.

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

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

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

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.

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

I'd have to agree with this analysis.

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

Agreed.

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

Not being a Docbook expert myself (Santa got me the book, but I've yet to
open it) I don't have much to say except your thoughts seem to agree with
many others I've heard.  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.

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

I've seen situations where the author chose not to pick a good license and
it ended up causing a lot of problems.  Many authors IMHO wrongly believe
that they need to maintain full control over their work, which almost
always ends up causing the doc to fail to be properly maintained.  The LDP
is full of these examples and there are many other.  A few people wise up
to this (The Linux Admin. Security Guide is one such example) but it would
be better to avoid it in the first place.  Sometimes no information is
better than bad/outdated info.  

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.

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

Well I would definately have to disagree there.  I know personally how
complicated such an infrastructure can be, and I'm happy to say it is very
doable.  My group, the Linux KB Project has been working on this for the
past 14 months.  While I'll be the first to admit that we're nowhere close
to where I had hoped we would be after 14 months of work, I am very happy
with where the project is headed and how things are developing.  As it
turns out, the biggest problem hasn't been technical or getting enough
computing/bandwidth resources to pull it off- it's been building a team
who is motivated enough to do it.  Good coders tend to have little time,
and vice-versa.  Patience is key as I am learning first hand.

Look for the Linux KB Project's source code and SQL schema to be made
availble in the next few weeks.

> > 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 guess I don't know how to do the standardization required to pull this
off without creating a dedicated oversight committee to manage it.  All
these groups have different opinions and needs relating to documentation.
Some groups are far more interested in the markup than the retrieval.  I
don't think a loose-nit group can create the needed colaboration required
to make it sucessful.  There's a lot more to documentation than writing-
people need to find it first before they can read it.

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

Again I'm confused about being anti-Linux slanted and yet using 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.

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.  But once you've got something to show off
and people realize it's power, you can start thinking bigger, because
people get motivated to help.  Seriously, the Linux kernel and the GNU
tools are FAR more ambitious than even a distributed documentation
retervial engine.

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

It's already unmanageable- do a search on Yahoo for some linux related
question- "Linux pop3 server" returns 13,000+ hits.  You may say they
should go someplace else for an answer, but right now there isn't a place
for one stop shopping for Linux documentation on the web.  It takes me
forever sometime to find what I'm looking for and I end up on a maillist
asking the same question someone else did last week because I can't find
the list archives. There really is a lot docs written by some Joe that he
put on his web site that most people never find because they don't know
where to look. At the same time, I couldn't agree more that we need more
authors writing good documentation.
 
> 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.

Agreed.

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

Perhaps you're right.  Problem is that I'm not interested in doing that.
:)  I'm far more interested in building an infrastructure to allow people
to find documentation that other people write regardless of its origin
than actually writing docs myself.  You may not agree with that, but I
think it is in your and everyone's best interest to work with people like
me because I fill a vaild need within the community.
 
> 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.

Sounds good.  I haven't been able to get a hold of Roger with SEUL yet, so
someone PLEASE setup a list for this!  Everytime someone responds to one
of my emails I get 3 copies and it's driving me nuts! 

--
Aaron Turner, Core Developer       http://vodka.linuxkb.org/~aturner/
Linux Knowledge Base Organization  http://linuxkb.org/
Because world domination requires quality open documentation.
aka: aturner@vicinity.com, aturner@pobox.com, ion_beam_head@ashtech.net
The difference between `Unstable' and `Usable' is only two characters: NT