[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [oswg-dis] [Fwd: Linux Documentation Infrastructure]
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:
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
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
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