[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.
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: email@example.com
> Resent-CC: recipient list not shown: ;
> Date: Fri, 07 Jan 2000 17:51:44 +0000
> From: Kim Lester <firstname.lastname@example.org>
> Organization: Datafusion Systems Pty Ltd
> To: email@example.com, firstname.lastname@example.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
> 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
> 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
> My casual list of "formats" currently includes:
> plain text - misc
> plain text - HOWTO (kind of a separate category)
> Tex (and variants)
> "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
> 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
> (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
> 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
> Where there are variations on a "standard" these should be separate so
> that they can change without invalidating a whole
> overview document.
> For example:
> 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.
> 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
> 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 email@example.com
> with a subject of "unsubscribe". Trouble? Contact firstname.lastname@example.org
"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 email@example.com
with a subject of "unsubscribe". Trouble? Contact firstname.lastname@example.org