Linux Documentation Infrastructure

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

Hi All,

[Note I've sent this to both LDP and Gnome groups. I selected these two
as they(you) seem to be the
current key areas of development.]

I've been around unix and linux a long time. I've done a lot of things
(programmer, hardware engineer and tech writing)

I believe that there are a few things that will make or break linux in
the greater community:
Good Documentation and Overall (Perceived) ease of use are two key
items.
The latter applies to Linux as a whole but also to the docs.

On to my point.
I know the history of unix, I know how all the documentation systems
evolved.
We need to stop evolving doc systems and bring it all together. Convert
(in some cases
on the fly) all docs into one infrastructure, whilst maintaining the
ability to handle
frequently changing doc text.

>From what I've seen LDP and GDP are addressing an important part of
getting a set of new docs up-to-date
and mostly in some sort of format. What I see as the next step is
unifying the strucutre.

Please bear with be while I explain, and if I've missed a key point (eg
this is being done) then
please a) bear with me b) enlighten me c) show me where.

I haven't made this a more formal structure as I wanted general comments
first.

My casual list of "formats" currently includes:

	plain text - misc
	plain text - HOWTO (kind of a separate category)
	man
	info
	ghelp
	Tex (and variants)
	html/sgml
	"toc" ?
	application-integrated help

My recommendation which I want to help with, (time permitting :-) ) is
to reduce the
number of formats to 3 initially and 2 later. I think fewer is
impractical, however
all formats would be presented though a similar front end so the
formatting would not
matter so much.

My suggested minimal formats are:
	*) sgml
	*) man
	*) plain-text

* The sgml is open to discussion, I simply picked that as it seems the
most flexible dynamic
language for inertactive manuals. 

* Man is there because there will always be man pages on unix systems.
Good or bad
	they're here to stay. They could be stored in say sgml format, but they
do need
	to be readable on an ascii terminal...

* Plain text. Well in an ideal world every hacker would write at least
an html-ish
ducument in their html-text editor, but being realsitic people will
still bash out
plain text for some time to come. Never-the-less I'd suggest a really
simple sgml template
(or whatever) that could be filled out (basic headings etc) that was so
easy to use
that there would be no real excuse for using plain-text.

There also ought to be a good formatter for printed material. ie it
should be possible
to reformat the docs on thefly for good quality printing (perhaps
sgml->(la)tex  - I haven't studied this much ??)

The second part of my suggestion is to more rigorously integrate the
documents into
a formalised infrastructure. There is a wealth of info available that is
jsut too hard
to find (even assuming you know it is there).

Part of the problem is integration, part is presentation.
Lets discuss this.

My first suggestion is to have a hierarchival system (not too deep) off
a main front help page. Assuming a netscape style navigator we'd have a
panel at left showing position in
hierarchy and panel at right showing relevant page (Actually rather like
the Microsoft
Development help system).

Lets take it further.
I think there shuld be a bookshelf (bit like SGI's offering)
Books could be added by any app into a supplied "hierarchy"

The hierarchy should be able to be cross refrernced in at least 3 ways
(and also via
a word search):
	By title
	By problem/concept/
	By program|module|group name


Further there should be several categories of bookselves.
My first thoughts are:

	1) End User
	    a) Desktop Environment
	    b) Major Applications
		Listed By Name
		Listed By Category (Word Process, Text Edit, Spreadsheet, Vector
Drawing)

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

	2) Administrator
	    a) Linux Installation
	      i)   General Linux Installation
	      ii)  <Vendor Specific> Installation
	      iii) <Vendor + Version Specific> Installation
	   
	    b) Hardware
	    c) LAN
	    d) Internet (SLIP/PPP etc)
	    e) User Accounts
	    f) Routine Maintenace
	    g) ...
	    .
	    z) (Man Pages)

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

		Gnome Developer

		KDE Developer

		Window Manager...

	4) Kernel (Developer etc)

	5) Hardware
		Board Level Docs (disks, graphics cards etc)


he hierarchy should be easy to navigate and not be too deep (say 4/5
levels max not including book chapters)

The documentation system should be dynamic in a couple of senses.
1) Adding a book (or even a chapter) into the document directory
hierarchy will
 effectively install that book - ie keep it simple. Reindexing might be
done as a cron job.
2) There should be known "template" areas into which certain classes of
docs should go.

Eg if you have KDE then a KDE book will go in the USER bookshelf under
the Desktop section.
Similarly a developer book in the "Desktop/Developer" section and of
course any KDE specific apps
in the Appslications/Utilities section.
Similarly the Gnome books would go in the same respective places. Once
might also keep a tag on sets of books
like KDE or Gnome s.t. If appropriate some sets could be turned off in
simple user display. This might be achievable
using BOOK path environment but  category tags in the docs would be
better.

3) RPM might be integrated as a "virtual" book, so that all installed
packages could be quickly interrogated (rpm -qil)
	The rpm "Group" tag would possibly be a good place to start listing
software by category until extended tags
	were created.

4) Application help (accessed within the app) should be common with the
bookshelp docs (maybe apart from very context sensitive
help).

Where there are variations on a "standard" these should be separate so
that they can change without invalidating a whole
overview document.
For example:
	PPP
	  General overview
	  Technical overview
	  Distribution Specific
	  Version Specific 

And to make the system even more useful hyperlinks could be made from
say technical overview, referring to "starting PPP"
into the Distrib/Version specific document, such that any changes in
starting ppp would not require re-editing the tech.
overview.

In some cases there might only be a version specific document, but at
least the concept of such a hierachy permits
bigger documents to remain valid for much longer. The only thing worse
than no documentation is WRONG documentation.

It would proably be best if the dir structure was fairly centralised
rather than using endless "MAN PATH" ideas.
Hoever NFS mounted books etc might require some use of paths.

The cross referencing is very important. As I mentioned above I've been
around unix for years and there are still
plenty of commands I just don't know about - and I have spent hours
hunting though bin dirs.
I one wrote a xref type guide for the research centre where I worked and
it was _really_ useful for all the users.
They could basically ask things like "How do I flip an image"/"Raster
Image Editing" or
"[What programs are available for] email".


Ideally I should be able to access the most useful chapter/page of
information within 4/5 clicks.
Cross referencing makes this possible and sgml/tags etc makes it
feasible.
I want be be able to access the documentation on say any unix
command/application to find out what it is or what
options to use etc in a few clicks.
If I want to edit an image or configure PPP, I want the relevant docs
(for my system) available within a few clicks.


Book updates would be automatically made available for download from the
net, users/ssyadmin would be flagged about
availability etc

I'd like to get all doc parties on board so that everyone is pulling
together. I cetainly don't want to start another
documentation project, that would be futile. But I do want to bring
everything together.
One way this _might_ work is that gnome developers open up their help
system to encompass more than just gnome and the LDP 
work with Gnome devs to get a good doc technology presentation system.

I've got many ofthe ideas, but it needs to be a community effort.

So how about it everyone ?

I look forward to your comments!


best regards

	Kim Lester
	Senior Engineer,
	Datafusion Systems Pty Ltd.


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