Re: Open Document Environment (ODE)

[Kim Lester <kim@dfusion.com.au>]

Hi Dave,

> >
> > 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'm sure you're smart enough to understand what I mean.
To spell it out. Each niche area has its own documentation system, which
is inefficient and unhelpful. Document systems are currently breeding
faster
than the supply ofdocuments.


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


I fully agree, but let's get to square one first - this group's only
24 hours old!

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

No real problem with that, as long as we get somewhere. There is always
the danger of finding something better/more exciting when one is halfway
through
an existing project. It is not helpful to restart every time.


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

Great we all look forward to their input, but two points
	a) this is bigger than just Linux....
	b) AFAIK _this_ is the  first public attempt get a diverse group
together.
		I may be wrong but some others' comments tend to confirm this.

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

OK OK, My broswer doesn't seem to do a good job of showing me the
columns.
As for typos, I wrote/sent it at 3 in the morning, don't you ever make
typos.
I hope you can find it in yourself to overlook my lack of typing
proficiency.


> > I propose creating an umbrella group of which all (hopefully) the
> > above groups would be members.
> >
 [...snip...]
>
> I would like to see the LDP be the lead group in this effort but all
> the groups need to become involved.


Hmm wouldn't happen to be a member of the LDP now would you !? :-)
Seriously though, as mentioned above this is bigger than Linux so
in that regard LDP wouldn'y be interested in being the lead member.
Besides there won't be a  sole lead member as it will upset the other
groups who would also feel they are equally important in their area.

Having said that I don't see any objection to have LDP be the key
implementer for the Linux specific portion of the documentation once
the "plan A" technical specs are bedded down.
The LPD may well be the only member group specifically interested
in the actual Linux docs (as opposed to say gnome apps or indexing)

BUT we haven't had any formal comments from the LDP yet, except Greg
Ferguson, but I think he's commented in a personal capacity so far)
What is your involvement with them Dave ?

As I've mentioned previously I'm not trying to negate existing groups
I'm trying to get a unified set of documentation standards in a
non-partisan manner.
 
> > 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)

IMHO you're being a little picky and have missed my point.
Open refers to the documentation
standard that I/we are trying to define. It is open in the sense that
we will all contribute to its creation and it will remain
open to changes by this (or possibly  anther future) group

Whether the documentation is free or not is not really our
concern. It may be the concern of member groups though, but that
is really a separate issue. 

As for "Plan-A XYZ" - the last time I heard anything called
the "Plan A- XYZ" was in a cartoon, and one always assumes there
will be a "Plan B" etc _when_ Plan A fails.
However I agree with you in as far as the first doc. standard
we define should be "Version 1.0" (or maybe 0.1 :-) )


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

I've expanded/clarified my point about "books" elsewhere
(and will post it again soon) On the specific point of Admin vs End
User,
well they are actually distinct search/topic categories.
True a user may wear both hats, and indeed may even wear two at once on
occasion but in my experience topics/problems often fall simply into

end user: how do I run this app? How do I send this email?
		How do I change my paintbrush colour?
admin: how do I install this app? How do I config sendmail? 
		How do I config by X display colour depth?
developer: what are the arguments to this func? etc
etc

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

  Agreed! docs can belong in multiple areas (discussed elsewhere)
> 
> >
> > 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.

New ways to organsie data are good, but _I_ believe some basic
constraints
are necessary (and not cumbersome). For example when discussing the
functioning
of a general application/utility don't  suddenly talk about the XYZ
distrubion 4.9
install path bug etc etc. Keep specific OS/Distribution/install issues
in separate
tannged doc sections (probably crosslinked) so that the ABC 9.1
distribution only
has to modify a few little bits and pieces to make it locally relevant
rather than
wade through the whole document editing out install path references etc
etc.
[And since the latter editing typically doesn't happen we end up with
inaccurate docs
	which are IMHO far worse than no docs in many cases]
> >
> >       Bookshelves could be added to via a web site.
> What about updating rather than adding.

Agreed this is an important issue

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

	Huh ? If you mean there shouldn't be any distinction between local and
	net books then I agree, except that it can be useful to optionally 
	identify _net_ based resources in some non-intrusive way
	(asterix after name etc) to indicate that the resource is remote and
	may be slower to access or unavailable (if not on net).
	Anyhow this is an implementation issue and I probably shouldn't have
	brought it up in the first place.

> >       All would appear to the user. (Maybe different colours etc ro indicate
> >       local/LAN/web access etc).
> >

[... snip ...]


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

I'm sure we're both relieved :-)

> suggest that this be thought out more thoroughly and rewritten.  But I
> appreciate your enthusiasm.

Naturally it all needs to be thought out more, which is the reason for
this list.
I/we appreciate your input too.
> 
>                         David Lawyer


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