409 lines
15 KiB
HTML
409 lines
15 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: Re: [oswg-dis] [Fwd: Linux Documentation Infrastructure] -->
|
|
<!--X-From-R13: Bnhy Xbarf <cwbarfNzrgnyno.hap.rqh> -->
|
|
<!--X-Date: Fri, 7 Jan 2000 14:33:34 -0500 (EST) -->
|
|
<!--X-Message-Id: Pine.GSO.4.05.10001071418330.7599-100000@titan.oit.unc.edu -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--X-Reference: 38763A0C.51E02F63@storm.ca -->
|
|
<!--X-Head-End-->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Re: [oswg-dis] [Fwd: Linux Documentation Infrastructure]</title>
|
|
<link rev="made" href="mailto:pjones@metalab.unc.edu">
|
|
</head>
|
|
<body>
|
|
<!--X-Body-Begin-->
|
|
<!--X-User-Header-->
|
|
<!--X-User-Header-End-->
|
|
<!--X-TopPNI-->
|
|
<hr>
|
|
[<a href="msg00994.html">Date Prev</a>][<a href="msg00999.html">Date Next</a>][<a href="msg01079.html">Thread Prev</a>][<a href="msg00999.html">Thread Next</a>][<a href="maillist.html#00996">Date Index</a>][<a href="threads.html#00996">Thread Index</a>]
|
|
<!--X-TopPNI-End-->
|
|
<!--X-MsgBody-->
|
|
<!--X-Subject-Header-Begin-->
|
|
<h1>Re: [oswg-dis] [Fwd: Linux Documentation Infrastructure]</h1>
|
|
<hr>
|
|
<!--X-Subject-Header-End-->
|
|
<!--X-Head-of-Message-->
|
|
<ul>
|
|
<li><em>To</em>: Sandy Harris <<A HREF="mailto:sandy@storm.ca">sandy@storm.ca</A>>, <A HREF="mailto:oswg-discuss@thepuffingroup.com">oswg-discuss@thepuffingroup.com</A></li>
|
|
<li><em>Subject</em>: Re: [oswg-dis] [Fwd: Linux Documentation Infrastructure]</li>
|
|
<li><em>From</em>: Paul Jones <<A HREF="mailto:pjones@metalab.unc.edu">pjones@metalab.unc.edu</A>></li>
|
|
<li><em>Date</em>: Fri, 7 Jan 2000 14:24:22 -0500 (EST)</li>
|
|
<li><em>Cc</em>: <A HREF="mailto:oswg-discuss@oswg.org">oswg-discuss@oswg.org</A>, <A HREF="mailto:osrt@metalab.unc.edu">osrt@metalab.unc.edu</A>, <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A>, LDP-Meta <<A HREF="mailto:ldp-meta@franklin.oit.unc.edu">ldp-meta@franklin.oit.unc.edu</A>>, <A HREF="mailto:kim@dfusion.com.au">kim@dfusion.com.au</A></li>
|
|
<li><em>In-reply-to</em>: <38763A0C.51E02F63@storm.ca></li>
|
|
<li><em>Resent-cc</em>: recipient list not shown: ;</li>
|
|
<li><em>Resent-date</em>: 7 Jan 2000 19:25:13 -0000</li>
|
|
<li><em>Resent-from</em>: <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A></li>
|
|
<li><em>Resent-message-id</em>: <lk3XZC.A.SBG.X2jd4@murphy></li>
|
|
<li><em>Resent-sender</em>: <A HREF="mailto:ldp-discuss-request@lists.debian.org">ldp-discuss-request@lists.debian.org</A></li>
|
|
</ul>
|
|
<!--X-Head-of-Message-End-->
|
|
<!--X-Head-Body-Sep-Begin-->
|
|
<hr>
|
|
<!--X-Head-Body-Sep-End-->
|
|
<!--X-Body-of-Message-->
|
|
<pre>
|
|
Sandy,
|
|
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:
|
|
<A HREF="http://metalab.unc.edu/osrt/projects.html">http://metalab.unc.edu/osrt/projects.html</A> 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
|
|
MetaLab
|
|
|
|
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
|
|
<A HREF="http://MetaLab.unc.edu/pjones/">http://MetaLab.unc.edu/pjones/</A> 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
|
|
|
|
</pre>
|
|
|
|
<!--X-Body-of-Message-End-->
|
|
<!--X-MsgBody-End-->
|
|
<!--X-Follow-Ups-->
|
|
<hr>
|
|
<ul><li><strong>Follow-Ups</strong>:
|
|
<ul>
|
|
<li><strong><a name="00999" href="msg00999.html">Re: [oswg-dis] [Fwd: Linux Documentation Infrastructure]</a></strong>
|
|
<ul><li><em>From:</em> Aaron Turner <aturner@linuxkb.org></li></ul></li>
|
|
</ul></li></ul>
|
|
<!--X-Follow-Ups-End-->
|
|
<!--X-References-->
|
|
<!--X-References-End-->
|
|
<!--X-BotPNI-->
|
|
<ul>
|
|
<li>Prev by Date:
|
|
<strong><a href="msg00994.html">Linux Documentation Infrastructure</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg00999.html">Re: [oswg-dis] [Fwd: Linux Documentation Infrastructure]</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg01079.html">Re: HOWTO vs mini-HOWTO [was: Linux Doc Infrastructure]</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg00999.html">Re: [oswg-dis] [Fwd: Linux Documentation Infrastructure]</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#00996"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#00996"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|