Re: Open Document Environment (ODE)

[<dave@lafn.org>]

On Sat, Jan 08, 2000 at 08:28:14AM +0000, Kim Lester wrote:
> 
> What we are trying to achieve
> =============================
> 
> To reiterate the point of this post:
> 
> Stop evolving documentation systems and bring all the documentation
> together in one easy to access form.
> 

If the evolution of Linux documentation ever stops then we're in big
trouble.  We need to lay out a plan for a projected future system of
documentatation and then one (or two) steps at a time progress toward
that goal.  However, as we come up with better ideas and technology,
the planned doc system needs to be changed from time-to-time.  I
think that while work is underway to complete plan-A, work should also
start on heading toward plan-B where plan-B is the successor to
plan-A.

It all needs to be flexible.  If plan-C (successor to plan-A) can be
implemented much faster if plan-B is scrapped then perhaps some plans
should never be implemented.  This is all a process of continuous
evolution an intergration.

> How
> ===
> 
> I'm not even going to attempt all this on my own, if the community can't
> be
> far-sighted enough and altrusitic enough to help then the task will be
> futile.

The LDP has at least of couple of people who have been looking into
the integration of Linux documentation: Peter Elliot
<axit@paradise.net.nz> and David Wheeler <dwheeler@ida.org>
One of LDP's goals mentioned in our manifesto is to integrate 
all Linux documentation.  That's exactly what you are proposing.

Next time could you limit line length to about 70 cols. so as to avoid
wrap arounds?  Also could you make less typos?

> I have joined the LDP, GDP, LKBP OSWG discussion groups and will cc this
> thread to
> all groups above (unless I get too many childish flames). I believe this
> is one of the few
> time when, what is effectively cross posting, is important to this
> community.
> 
> I propose creating an umbrella group of which all (hopefully) the
> above groups would be members.
> 
> This group would coordinate the infra-structure of all documentation,
> (ie the "ideal" format, the permitted formats, the indexing/xref'ing
> scheme
> papaer output etc).
> Once this has been dertermined (with all your input and expertise)
> everyone
> can, more-or-less get on with waht they were doing before, but in this
> agreed
> framework.
> 
I would like to see the LDP be the lead group in this effort but all
the groups need to become involved.

> Scope of Group
> ==============
> 
> I've tentatively named the umbrella group "Open Documentation
> Environment (ODE)"

I don't like this name.  I think you should replace "Open" with
"Free".  All non-free documentation is "open" since you can look at it
once you buy it.  It's a different story for programs since for most
commercial software you can't look at the code.  The "Open Source
Definition (TM)" applies only to software and what it defines is
ambiguous and not exactly free.  So I propose you call it say "Plan-A
Linux Documentation System".  You need to have version numbers or the
like (A, B, C, ... or numeric)

> General Design Goals
> ====================
> 
> * Implementation of a Bookshelf concept
> 	A bookshelp is a simple visual pardigm.
> 	There would be bookselves in a range of categories (eg End User,
> Administrator, Developer).

This doesn't work very well for Linux since each person that puts
Linux on their PC is both an Administrator and End User.  When they
start fixing bugs and compiling the fix they also become a Developer.

> 	Only the relevant Bookshelves need to be displayed (by default) for any
> user. Searches
> 	would also be confined to selected bookshelves.

What about docs that belong to multiple bookshelves?

> 
> 	Books on any topic could be added to a bookshelf. General book writing
> guidelines
> 	would keep books releveant to their category.

I don't think this should be imposed on authors.  Often new ways to
organize knowledge is desirable.

> 	
> 	Bookshelves could be added to via a web site.
What about updating rather than adding.

> 	Thus a user has a list of available books.
> 	Books would be installed wither locally, on a LAN or on the net.

I like to see a book called a book.

> 	All would appear to the user. (Maybe different colours etc ro indicate
> 	local/LAN/web access etc).
> 
> 	All this would be transparent to the user. Available book contents
> pages/indexes would automatically
> 	be downloaded and available for perusal. If a WEB based book looked
> interesting then either the whole
> 	book or just a few pages could be downloaded asrequired.
> 
> 	Indexing/cross referencing should also provide the ability to show info
> (maybe in a pastel hue) of

I suggest that this also be possible also on dumb teminals by use of
bold, inverse video, etc.  If this is not feasible you could have a
system of symbols to mark the "color" of a word.

> 	information on say software that is available but not installed.
> 	So many time users have not been aware of installed software let alone
> software avaialble on the net.
> 	For example if I wanted an image editor.
> 	I could ask for a search on "Image Editors (Raster)" and be told that I
> had say one on my system and
> 	3 avaialble for download from the net. "Hmmm the installed one doesn't
> do what I wnat. But this other one
> 	interests me I'll download its overview page and maybe help contents.
> Looks good, ok go get it."
> 
> 	I have dozens (probably hundreds of programs installed on my system)
> that I don't use.
> 	Why are they there? 
> 	Because
> 		a) I might need them
> 		b) I don't know they're there.
> 		c) I don't need them but they were installed anyway because I didn't
> know any better
> 
> 	It would be so much better to install just a few "common" apps and ta
> good documetnation system. 
> 	Then have the others books/apps installed on demand.
> 	With the bookshelf system we have access to the docs of programs not
> installed so we don't ahve to worry about
> 	missing out (and often installing everything just to be sure)!
> 	Then we'd install just what we needed.
> 
> 
> 	NOTE: In the future this could also support download of commercial
> books/sw for a fee, but we
> 	won't deal with that for now.
> 
> 
> 	Books might actually consist of docuemnts that appear in several places
> as relevant.
> 	Eg a technical chapter on PPP configuration might appear as a
> document/book under Installation
> 	and also under Administration and even uder Operating System
> (internals). ALthough one has
> 	to be careful it can be taken too far. It is not a substitude for
> sloppy categorisation!

Referencing docs covering the same topic each with a different scope
and style and calling it a "book" doesn't seem right.

This point is less than 1/3 the way though and I'm quiting here.  I
suggest that this be thought out more thoroughly and rewritten.  But I
appreciate your enthusiasm.

			David Lawyer


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