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