[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [oswg-dis] [Fwd: Linux Documentation Infrastructure]

We've already started a metadata template and checker for Open Source
documentation that creates XML and will allow, in the near future, author
correction and database searching etc.
Take a look at what we've done so far at:
http://metalab.unc.edu/osrt/projects.html and check out the description of
metadata elements, DTD, and template there. We'd love to have others
involved and to have your input and participation.
Paul Jones

On Fri, 7 Jan 2000, Sandy Harris wrote:

> Mehinks this should also be seen by people on the Open Software Writer's
> Group list, so I'm forwarding there.
> Likely replies should go to the original lists.
> -------- Original Message --------
> Subject: Linux Documentation Infrastructure
> Resent-Date: 7 Jan 2000 17:53:24 -0000
> Resent-From: ldp-discuss@lists.debian.org
> Resent-CC: recipient list not shown: ;
> Date: Fri, 07 Jan 2000 17:51:44 +0000
> From: Kim Lester <kim@dfusion.com.au>
> Organization: Datafusion Systems Pty Ltd
> To: ldp-discuss@lists.debian.org, gnome-doc-list@gnome.org
> 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

                             Paul Jones
   "We must protect our precious bodily fluids!" General Jack D Ripper
http://MetaLab.unc.edu/pjones/ at the Site Formerly Known As SunSITE.unc.edu
  pjones@MetaLab.unc.edu   voice: (919) 962-7600     fax: (919) 962-8071 

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