ODE Summary Report #1


Kim Lester (kim@dfusion.com.au)
Tue, 11 Jan 2000 02:57:54 +0000


                                        ODE Summary Report #1
                                        =====================
Welcome All,

        Thanks to Deb Richardson (deb@linuxcare.com) for setting this
        list up.
        
        This is a forum for discussing the concepts
        of a Free/Open Standards Document/indexing/packaging/
        distribution etc
        
        The overall purpose is to stop everyone evolving incompatible
        doc systems.
        
        My (Kim's) reason for starting this whole debate was to
        encourage a common open system document organisation/indexing
        framework for the currently separate OS/application documentation
        groups to take on board and use in their own area of interest.
        
        Why? Computer users need to get easy and uniform help on their
        problems and to avoid us developers/writers etc having to
        repeat/rewrite documents.

        The actual documents are of less importance
        to this group,that's the domain of the documenting member
        groups. However suggestions for improvements in existing
        (OS specific) documentation organisation might be
        worthwhile since the group is still small.
        
        The standards developed here should encourage, if not enforce,
        higher quality levels in the actual documentation structure.
        

        Scope
        =====
        
        This is open to debate (as is everything else).

        There is no reason for not having an ambitious scope but it
        should be broken into manageoable phases.
        Maybe the first draft solution won't address all the issues as
        long as it does not hinder the remainder it can still be
        implemented whilst subsequent stages are implemented.
        
        I'd ideally like us get a workable draft out within say a few
        months ?
        
        
        Social Scope
        ------------
        
        The "social scope" was meant to be broad,including OSes like:
        BSD, Linux, BEOS, even companies like SGI etc if interested
        It would encompass GNU docs, GNOME, KDE, Specific
        Distributions etc.
        
        The only limit is practical, we may not be able to get all
        the above groups to agree (ever tried herding cats ?).
        At least if we can get agreement in one domain then it is a
        good start.
        
        So we shouldn't limit ourselves to just Linux for example.
        However it might be that once decisions are made one of the
        existing Linux Doc groups takes those agreements on board and
        handles the Linux issues with co-operation from other groups.
        Similarly the BSD people would work with their groups.
        
        Ideally for example a program written and documented under
        BSD, then ported to Linux would already have format
        compatible documentation and only OS specific sections would
        need changing.
        
        Technical Scope
        ---------------
        
        Development of these areas might be done in parallel or broken
        into longer term phases.
        Technical solutions should not preclude any of these areas
        working efficiently.
        
        * Definition of a primary document distribution format
        
        * Selection of acceptable document source formats
        
        * Resolution of versioning and language issues
        
        * Development of indexing/categorization requirements
                (to be implemented by relevant member groups)
        
        * Outline local/network document access protocols
                (to be implemented by relevant member groups)
        
        * Implementation of an indexing/categorization technology

        * Consideration of browser/presentation software technology
        
        
        Misc Goals
        ----------
        
         * Leverage existing software and standards where possible.
         
         * Avoid an overly complex/over-engineered structure
         
         * Minimise administration overhead.
         
         * Streamline from writers perspective.
                 ie A system simple enough that anyone wanting to write
                 a document can do so with the minimum of software
                 tools and minimum of fuss.
        

        Other Issues
        ------------
        
         * Licensing (ugh!) - perhaps we should dump the license
                 issue and concentrate on the documentation standards.
                 Document collectors can handle that one separately.
                 All those in favour say aye !
                 
         * Writing tools
         * GUI paradigm
         * Text only interface compatibility
         * Printing compatibility - should print nicely if required.

        Structure of the "Umbrella" Group
        =================================
        
        I used the term umbrella group which has made a few people
        "nervous". Please don't think the aim is to control other
        groups. I am a coordination freak not a control freak :-)
        
        This group is more of a virtual/meta group consisting of
        all interested parties.
        Whether it takes the form of an actual organisation or just
        this mailing list is not critical (your choice). What is
        important is that we communicate and move forward in make
        decisions. A mailing list is simplest but often people need
        more structure than this to get things done.
        
        _If_ we can manage with just this list then great!
        At some point however, once we get some decisions made, there
        probably ought to be a site set up for people to view the
        agreed standards. A mailing list is not enough for this.
        
        As I've mentioned previously, and it seems I'm going to have
        to keep saying it until people understand/believe:
        
        *** I'm not trying to negate existing groups I'm trying to ***
        *** promote a unified set of documentation standards, so ***
        *** that the existing groups can write compatible ***
        *** documentation. ***
        
        There will be discussions, perhaps heated, but try to remember
        why we are doing this :-)

        
        GROUPS
        ======
        
        The following groups have been informed of this list,
        although some of these groups may not (yet?) be
        aware/interested in this list.
        
        It would be useful to find out who on this list has some
        connection with which group. Partly to help understand your
        viewpoint and partly to ensure interested groups are not
        missing out.
        
        Please correct me if I have got your interests wrong and
        submit a correction.
        Maybe a representative of each group could summarise the
        particular stengths of their group.
        
        In alphabetical order:

        * Free/Net/Open BSD ??
        
        * Debian Documentation Project (DDP) www.debian.org/~elphick/ddp/
                Key Interest: Document the Debian distribution of Linux
                
        * Gnome Documentation Project: www.gnome.org/gdp
                Key Interest: gnome app software, gnome help browser

        * Linux Knowledge Base Project www.linuxkb.org/
                Key Interest: categorization/xref/search engines,
                                                multi format

        * Linux Documentation Project (LDP) www.linuxdoc.org
                Key Interests: Coordinating Linux Documentation
                
        * Open Source Research Team (OSRT) metalab.unc.edu/osrt/projects.html
                Key Interest: XML doc format, versioning searching
        
        * Open Software Writers Group www.oswg.org
                Key Interest: Improve quality/quantity of open/free doc
        
        * RedHat Documentation ??
        
        * SGI ??

        The mailing lists that I am currently aware of include. I have
        not posted to all these, perhaps other interested parties can
        keep relevevant groups up to date.
        
                     ldp-discuss@lists.debian.org
                     ldp-discuss@lists.linuxdoc.org
                     debian-doc@lists.debian.org
                     oswg-discuss@oswg.org
                     ldp-meta@franklin.oit.unc.edu
                     osrt@metalab.unc.edu
                     linuxkb-discuss@seul.org
                     gnome-doc-list@gnome.org
        
        
        SOFTWARE
        ========
        
        Existing Document Viewing Tools/Software
        ----------------------------------------
        Web browsers: primarily HTML (gui/text)
        Amaya browser/editor (w3c.org)
        texInfo
        
        
        
        Format Converters
        -----------------
        info2html (primitive/ uses info output ?)
        tex2html (uses .texi source ?)
        makeinfo --html (uses .texi source ?)
        
        man2html
        html2man (?)

        sgml2html
        
        
        Potential Format Converters
        ---------------------------
        docbook2texi // docbook2info
        
        
        
        
        Existing Document Architectures
        ===============================

        HTML
        
        SGML
            - Docbook DTD
            - Linuxdoc DTD
        
        XML
        
        texInfo
        
                
        
        SUMMARY TO DATE
        ===============
        
        My summary (hopefully not too biased) of group sentiment so far:
        
        * Writing good docs alone is not enough.
                They need to be easily/quickly "findable".

        * Existing distribution structure is not satisfactory.
        
        * Documents should not be monolithic but broken up
                into small topics which can be chained togther
                by the presentation tool/search engine as required

        * Users need a consistent/uniform interface to accessing
                documentation
        
        * Indexing/Searching methods need to permit following searches:
                text search
                by program name
                by issue/problem
                by topic/category
                by installed file name (discuss, bit like man sect. 5 + rpm)

        * Docs are likely to be installed on local machine and new
                ones/updates available on the net.

        * Currently many useful sources of docs spread out on net.
                [Kim] suggests that maybe a central repository be
                set up to accumulate key documents.
                [Others] warn of admin overheads of such a system.
                
        * Importance of _correct_ keywords/indexing of documents.
        
        * Need to interface to common web browsers.
        
        * Need to support text based interface (eg Lync web browser)
        
        * Need to support selected input formats
        
        * Unified ditribution format (Hopefully just one but...)
          ie All docs must be accessible through a truly unified,
                  non-redundant cross-indexed system.
                  
                Personal preferences probably require converters to
                other formats eg texInfo - its ok to convert en-mass
                for those who want that ?
                
        
        * Much info exists in texInfo format. This format needs to be
                supported either natively or via completely automated
                conversion tools.
                [Kim] suggests that the content would remain unchanged
                Possibly the indexing/links system _might_ need
                slight adjustment.
        
        * Some/many writers will not change from texInfo.
        
        * [Karl E] "dislike of HTML as browsers can't search through
                all files at once"
          [Kim] Not sure I quite understand, do you mean "grep" like
                   function? Need to resolve this
          [Martin W] Use Htgrep ( http://iamwww.unibe.ch/~scg/Src/ )
                   
                  
        * Need and author/editor guide/structure to define
                document conventions and provide a (simple)
                framework. Documents should (ultimately) conform
                to such a system.
        
        * Suggestion that we wait until X3C standards are defined
                (XLink, XPointer, XPath etc) in aound 2001 (??).
          [Kim] I don't think there is any point twiddling our thumbs
          for a year. Standards are
                  always being defined and refined. Instead I suggest
                  we pick a flexible format (eg XML)
                  take on board the initial recommendations and when the
                  standards come out (xx years) we consider doing an
                  auto conversion to the new standards if worth while.
                  (If we insulate the writer sufficiently from much
                  complexity - as happens with modern HTML editors the
                  writer pain will be minimal)
        
        * Effort needs to be put in to categorising existing
                doucmentation and possibly splitting it up so that
                app info is separate from platform specific info etc.
         [Kim] Whilst this could amount to a significant amount of
                 work it is things which can be off-loaded to the
                 authors and specific doc interest groups. I expect
                 much of the texInfo doc is already sufficiently
                 categorised ?

        * A central index/catalog repository of info is good
                (whether local or net or both)
        
        * Searching over the net _can_ be quite slow so consider local
                index etc (updated from net) ?
        
        * The docs themselves should probably be at a central site
                because it is no good having a great index if the
                links break (Anyone never be frustrated by a '404' !?)
                
        * Docs/index etc would potentially be available on CDROM.
                Need to bear this in mind.
        
        * Several "votes" for SGML/XML DocBook format. Others ??
        
        
        * [Morten] If xxML were used, categorisation could be encoded as a
          comment, eg:
          
           <!-- Group: software/configuration -->
           <!-- Keywords: sendmail:mail:e-mail:Internet Connectivity: -->
        
           [Kim] Sounds reasonable. I'm not a SGML/XML guru though.
                   What about special/explicit tags for such things?
                   How does this compare with use of key-tags hidden in comments.
                Part of this project would be to define such keywords
                making them as compatible with other standards as practical.
                
        * Document history/traceability
        
        
        
        
        Well I think that's enough to be going on with.
        Comments everyone....

        regards
        
        
                Kim Lester



This archive was generated by hypermail 2.0b3 on Mon Jan 10 2000 - 22:00:41 EST