[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