Open Document Environment (ODE)

[Kim Lester <kim dfusion com au>]

Thanks to all those who responsed! I've taken your ideas on board and
included them below. Keep it up.
To those of you who haven't had a chance yet, please respond and
come on board. Now is the time before recommendations get set in stone!



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.

Let me summarise so far:

A number ofgroups are working on mostly different aspects 
of either documentation itself or documentation retrieval etc.


Who
===

The organisations that I am now aware of include:

Linux Documaentation Project (LDP)	http://www.ldp.org
Linux Knowledge Base Project		http://www.linuxkb.org
Gnome Documentation Project (GDP)	http://www.gnome.org
Open Source Research Team		http://metalab.unc.edu/osrt/projects.html
Open Software Writers Group		http://www/oswg.org

Interest has also been shown by an electronic publisher to produce
hardcopy versions of the resulting high-quality documentation.

If you know of any (non-commerical) doc group that I've left out please
let me/them know.


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.
I'd at least hope for enlightened self-interest! :-)

Ultimately we could create a new mailing list covering all member
groups, perhaps
with the other existing groups as subgroups of this.
I'm currently forcing it on you for now as we keep getting new special
interest document groups and no-one appears to have shown interest in
cooperating.

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.

To those of you in advance who are going to object to my cross posting
invading
your personal world, I'd say look around you. The best things in life,
the web,
Linux etc were made through cooperation. Maybe we all have to give a
little ground
but the result will be far better than any one group could have achieved
on its own.

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.


WHY am I trying to do this ?
============================

This is a serious attempt at getting badly needed coordination. It is
NOT about control.
I am in no way interested in controlling anyone. I am interested in
coordinating
a unified effort with everyones help.

I respect that each one of the above groups has slighty different goals.
This is actually good as the task is large. If we change "goals" to
"areas of responsibility" I think we could really get somewhere -
together.

I respect the amount of effort many of you have put in,
in your own areas and groups. I do not wish to detract from that,
nor do I wish to take away anything from the individual groups.

It will take me a little while to digest all the different group areas,
so bear
with me on this, and help me out by becoming part of this discussion.


NOTE: All the following is open to comment/suggestion. This has to be a
community effort. I want to encourange informed debate, but not create
a free-for-all anything-goes environment. This is counter-productive.


Scope of Group
==============

I've tentatively named the umbrella group "Open Documentation
Environment (ODE)"
Ode is also a relevant word.
(Maybe for the trekkers amongst you it should be called "ODO" Open Doc
Org.
after all ODO is very flexible.... :-) )

I wanted to avoid using one of the existing group's names
as experience indicates this leads to ownership issues.
Humans can be difficult at times. Sigh!

My initial area of interest was Linux and its software. However I
realised that
software like Gnome etc are broader than just linux. This is fine as the
document infrastructure I'm proposing supports that. It does need to be
said
though that the system _may_ end up being used in other areas, we should
encourage
this and not be biased against it.

In the first instance I suspect that most of the work will be done in
the linux area though.


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).
	Only the relevant Bookshelves need to be displayed (by default) for any
user. Searches
	would also be confined to selected bookshelves.

	Books on any topic could be added to a bookshelf. General book writing
guidelines
	would keep books releveant to their category.
	
	Bookshelves could be added to via a web site.
	Thus a user has a list of available books.
	Books would be installed wither locally, on a LAN or on the net.
	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
	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!

	SGI have/had a reasonable bookshelp concept, it would be useful to
examine this for ideas.

* All books/documents appear to be in ONE format (from reader's
perspective).
	Ideally this means look at feel similar.

	I'm not suggesting that we enforce a specific look and feel,
	but that we conform to a set of directives (eg all titles have a TITLE
tag)
	such that all titles can be made to look similar.

	Recommend a default look and feel (X windowing system made the mistake
of
	not recommending a look and feel. The result was chaos for many years!)

	Books in a range of other formats are converted (one-time or
on-the-fly) into
	the common format


Human Issues
============

	There are no doubt going to be some religous wars on formats.
	Some would rather die than give up their favourite format.
	Hopefully the converters will address some of these issues and permit
	personal preferences to prevail.

	HOWEVER. What I want us to achieve is something better for everyone.
	If you'd rather defend your personal rights to the death and refuse to
be
	part of something bigger then I wish you good luck. But such attitudes
tend
	to result in individuals and groups pushed towards the fringes rather
than being
	in the main stream success.

	There are still people out there who think CPM (an early OS) is the
best thing ever.
	Well I can appreciate their right to that belief, but they aren't
interested moving forward.
	We will probably all have to give some ground for a common good...
	If you have a technically valid issue, join in the discussion and lets
work it out!
	

Working Group Tasks
===================

The group should examine the skills and technologies of a) group
members, b) other technology
and come up with recommendations for:

	Initial Documentation Areas
		- split into broad subject areas right down to key topics.

	Documentation Technology
		- determine the best OUTPUT technology to support
			a) Good presentation
			b) hierarchical doc structure
			c) Extensive cross-referencing
			d) High Quality Printing

		- determine how best to massage existing formats into the new format.
			Identify existing documetn formats.
			(Important docs would need editing, others could be auto
			processed at least initially)

	Documentation "Browser" Technology.
		- determine specs for a world-class doc viewer/search-engine/etc
			that fits the chosen OUTPUT technology
		- take into account existing software but not be hamstrung by it.
		- might support basic browsing with existing software and more
			advanced functions with an open-source customised browser.
		- include any xref/search engine


Legal Stuff
===========

	I hate layers, I hate legal documents. They often end up spoiling
things.
	Everything seems to require some legal statement though..

	The author maintains ownership of his/her document and authors name
must always be included.
	Perhaps provide a history log of editors. If a doc becomes inaccurate
then editing
	must be permitted regardless. (Seems a bit hard, but I'm tired of
inaccurate docs
	that don't get changed). Note sure about aesthetic editing.
	
	I'm not sure whether docs should be allowedto have individual Licenses.
Maybe just permit
	one or two common licenses (GNU ?). Licenses should permit free
use/printing of docs  for personal
	use. Non-profit distribution must also be royalty free. For-profit
distribution (eg proper publishing)
	should perhaps be based on typical industry royalties and then
percentages given either to key authors
	and/or the remainder put in something like an ODE non-rpofit fund to
pay for even better doc.

	I'm aware of two other doc licenses: Open Content License and GNU Free
Documentation License.
	I haven't read them yet.

	I'd welcome any better suggestions.



The following are a zeroth order draft of the above areas, as somewhere
to start.

NOTE: To those of you not into Linux, please bear with me I have
	to start the discussion somewhere. I'd welcome contributions!

Initial Documentation Areas
===========================

	Note keeps apps and utlitities separate from OS implementations where
possible.
	eg the unix "date" command whilst compiled for and available under
Linux is also
	available on any system compiling GNU tools.
	It should thus be available in a cross ref under "Linux->Commands" but
if the linux
	specific docs are removed then it ought to remain available under the
more general
	Unix->Commands.
	Note I haven't fully developed a plan for this yet.


    Initial Bookshelves
    -------------------

	System Installation
	General User Guide
	Tools and Applications
	Administration

	Application Software Developer
	Operating System
	Operating System Developer
	Hardware


	There are a number of ways to divide bookshelves.
	I have initially divided them based on gut feeling from years of
personal experience
	and problem solving for users.

	Tools and Apps are separate as all levels of users need to look up this
info.

	Most of the bookshelves would have a combination of books that might
come under
	the categories of
	    Guides
	    Reference


	System Installation
	-------------------
	I guess this might be a separate bookshelf although parts of it come
under Admin and
	parts user.
        
	Linux Installation
              i)   General Linux Installation
              ii)  <Vendor Specific> Installation
              iii) <Vendor + Version Specific> Installation/Notes
	      iv)  Errata
  

	General User Guide
	------------------

       	   a) Desktop Environment
		Current (ie what is being run now)
		Others )other availabe environments)

	This should contain all the "getting to know you" stuff
	In particular it should distinguish between the current installed
software and
	other options.

	It is important to distinguish the current environement setup from
possible setups.
	It is too mcuh to expect a novice user to know that he/she is currently
running
	Enlightenment WM on Gnome on X on Unix. Even I forget which WM I'm
running half
	the time!  The "Other" section would list alternives that the user
might prefer
	to explore along with references to how to setup/install/activate these
alternatives.
 


	Tools and Applications
	----------------------
            a) Major Applications
                Listed By Name
                Xref By Category (Word Process, Text Edit, Spreadsheet,
Drawing)

            b) Utilities/Tools
                Listed by Name
                Listed by Category (Disk, Net, File Manip, Text Manip,
etc)
                (Listed By Problem/Solution)

	    c) Man pages

        Administration
	--------------

	  Key Topics/Overview

	  Tasks by Topic
            a) Logs
            b) LAN
            c) Internet (SLIP/PPP etc)
            d) User Accounts
            e) Routine Maintenace
	    f) Hardware Problems
            g) ...
            .
            z) (Man Pages)

	
        Application Software Developer
	------------------------------
                Language Summary/Overviews
                Languages...
                Debuggers
                (Man Pages)
        
                X11 Developer

                Gnome Developer
		    Overview
		    Style Guide
		    API Reference

                KDE Developer

                Window Manager...

  
        Hardware
                Board Level Docs (disks, graphics cards etc)


	etc

	
	
	

Documentation Technology
========================

    Existing doc formats
    --------------------	
        plain text
	   - some HOWTOs (semi structured)
	   - READMEs/Changes/INSTALL instructions etc (semi structured)
	   - FAQs (semi structured)
	   - misc notes
        man pages
	   - all command line unix commands
	custom application help
        HTML
	   - some HOWTOs
	   - some FAQs
	   - Introductory Docs
	   - Distribution docs (eg RedHat)
	texInfo
        SGML
	XML
	DocBook DTD (XML/SGML)
	(RPM)


    Proposed doc "OUTPUT" format
    ----------------------------
	It has bveen suggested that there really isn't any excuse for
	plain text any more as a plain doc can be made at least HTML
	compliant with a couple fo minutes extra work.

	There are also man/html converters around so the man page
	format may not be as sacrosanct as once thoguht.
	(being able to see good ascii output when typing "man fred"
	is still a requirement though.

	It thus seems feasible to have a single "meta format".
	Ideally all documents would be in this format, and in time
	they might be, but for now there need to be converters from
	existing formats (may such beasts already exist).

	Whatever standard we agree upon as the meta/Output format
	it should be extensible and flexible enough to adapt to things
	that we havent thought of yet.



    Converters from existing formats to "OUTPUT" format
    ---------------------------------------------------
	Some existing document systems are extensive enough that
	conversion to a new format by hand could be prohibitive.

	Some docs may be converted one-time into the new format
	other (which are still being edited by other groups who
	can't/won't change formats might have to be converted
	on-the-fly from their native formats.

	Other docs should just be changed, either by authors or group
	members. Once there is enough momentum I envisage that encouraging
	many existing doc. maintainers to put in a little extra work for
	the good of all will become easier.

	My first guess for an output format would be XML possibly using the
	DocBook DTD (http://docbook.org/) maybe with some extra tags.

    Issues
    ------
	Ease of adding/copying/indexing books
	Support transfer of just sections of a book (eg specific
sections/pages) as 
	required to be downloaded from the web - ie don't require whole book.

	It owuld be good to provide links from within apps to a common doc.
set.
	Sometimes apps have internal help systems which are
	a) uselss as they tell you nothing much
	b) very helpful but not accessible outside the app.

	Lets pursue a policy of "write once, read many" (WORM - yes I know it
comes from MO technology)
	ie maximise the access to any documentation. This could include context
sensitive tags
	activated within an application that open up to a specific part of the
application book.

    RPM
    ---
	Open to debate, but I added RPM to the "doc" list as it is becoming an
	increasingly important tool for the distribution of software.
	For those of you not familiar with it, RPM is a software distribution
tool
	that pacakges up the files in a software/document/etc sub-system along
with
	an info summary and installation scripts.

	RPM could be important in two areas:
	1) it could be a convenient ODE Book distribution/installation/update
mechanim.
	2) it could provide a useful method of creating a "virtual" book of
installed software.

	Of course installed software should have documentation pages under the
new system but in
	the meantime RPM has at least a few lines of comments about each
package and a broad category
	for that package (eg Applications/Internet).



Browser Technology
==================

	Leverage existing efforts.

    Indexing/Cross Referencing
    --------------------------
	Produce access to a comprehensive indexing system and permuted index
etc.
	Here the expertise of the OSoRT group will greatly help!
	Indexing by
	     Book/Doc Title
	     book text
	     concept keywords/category (eg Text Editors->Graphical"  or "PPP
Problems")
	

	The Gnome Help Browser might be a good GUI software vehicle with which
to start experimenting.

    Initial GUI Thoughts
    --------------------

	I'd like to see a doc browser a bit like one of MSoft's (eeek!)
development doc system.
	The key idea is a panel at the left with a tree view and the document
panel at the right.
	Might also have a separate document/book-chapter/section broswer to
quickly pick out sections
	in the current book.









	regards
		Kim Lester