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


Deb Richardson (deb@linuxcare.com)
Mon, 10 Jan 2000 02:10:42 -0500


"Jeremy D. Zawodny" wrote:
> > 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.
>
> Depends on your logic, I suppose. In *MY* mind, the logical answer is:
>
> Whoever writes the best Apache documentation.
>
> Just like selecting a Linux distribution or a BSD flavor. I pick the
> one that I do because I believe it to be the best for my needs.

Granted, the best code and the best docs will be the most commonly
used. On the other hand, the Apache Group is best suited to write a
general core manual for their server. Someone else, however, might
write a series of really kick-ass HOWTOs related to configuring and
optimizing the Apache server on a RedHat 6.1 system. Additionally,
someone else might write a great FAQ about using Apache with Zope. All
of these are documents that are useful to various people, depending on
what they're trying to accomplish. But the manual will exist as part of
the Apache project, the HOWTOs might be part of the OSWG documentation
set, the FAQ might be part of the Zope web site. Which document is
"best" depends on what you're trying to accomplish.

[snip]
 
> Yet I can still find the software I want for them by visiting a very
> few sites, such as freshmeat. It doesn't take all day. Let's just make
> the same true for documentation, be it OS or application
> documentation.
>
> Is that your aim? That's where I'd like to see things go.

I think that this is generally where the OSRT is going with their
meta-information project (the card-catalog idea). A single location
where users can go to search for and find the documentation they need.
Ideally the information contained by the site will be contributed to and
maintained by people from all the different documentation projects. So,
yeah, sort of a Freshmeat for Docs, with a very powerful information
database as its back end.

> Granted, I've only contributed one HOWTO to the LDP, but this stuff
> sounds as if it is getting out of hand--people are trying to over-plan
> everything, with committees, councils, advisory groups, and
> whatnot. "We" seem to be advocating a very large hammer to squash what
> is ultimately a rather small bug when it is not considered in
> isolation.

I agree. Not just a large hammer, but an overly complex hammer with far
too many moving parts. What we need is a nicely weighted, well-crafted,
and simple tool. I believe that the OSRT is working on the development
of that tool.

There are also a whole variety of other bugs we have to figure out how
to squash in the mean time, including: how to get more open docs
written, how to develop and maintain open channels of communication
between the various projects, how to get translations written and
verified for as many languages and packages as possible, how to improve
the general quality of documents that are produced, how to develop and
manage large-scale collaborative documents, how to get missing or
out-of-date man pages written and updated and improved, how to make
DocBook more approachable for new users...etc.

Open Source documentation, when you take a good long look at it, is a
bit of a mess at the moment :)

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



This archive was generated by hypermail 2.0b3 on Mon Jan 10 2000 - 02:06:29 EST