Re: ODE Summary Report #1


Marc Britten (yugami@usxchange.net)
Tue, 11 Jan 2000 01:16:52 -0500


Kim Lester wrote:

> * 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 !

Unfortunatly, if the central repository comes into this(and I do think
that is a fairly good idea) licensing will become an issue right away.
I'm not rules lawyer or anything like that, but the potential for screw
ups on this is huge, we may need to focus on this issue as well.

 
> * Writing tools
> * GUI paradigm
> * Text only interface compatibility
> * Printing compatibility - should print nicely if required.

GUI/Text only shouldn't be a problem if we focus on a good format with a
few rules about layout, then all we need to do is supply the rules, or
maybe a library to program with.
 
> 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 :-)

I do hope we get over this right away, what I've seen discussed so far
is not a bad thing.
 
> * Documents should not be monolithic but broken up
> into small topics which can be chained togther
> by the presentation tool/search engine as required

you ever try to print something that is broken up into bits and pieces?
I'm afraid that print is not dead. I still prefer a hard copy in my
lap/on my desk for reference while doing complex tasks.

however I agree that these are bad to scan through quickly also, perhaps
a method of doing both(or atleast printing out the whole thing) will be
necessary?
 
> * 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)

its been brought up before, but I would like to reiterate, that SGI and
Sun both have good desktop utilities for searching installed docs.
 
> * Need to interface to common web browsers.

need to have the ability to output HTML is a better way of saying it, if
we use(off the top of my head) tex, then the tex2html tool should be
good enough
 
> * 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)

waiting is never a good thing(well every once in a while). There are
very few cases of real wasted effort, at least you learned from your
mistakes the first time around, and now that the new stuff is out you
can get to it quicker.
 
> * 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 ?

Linux Documentation Project, Linux Knowledge Base, etc already have
systems setup to handle this, LKB's source for their site/search engine
setup is open source so other OS groups that don't have a good setup can
just work from this.
 
> * A central index/catalog repository of info is good
> (whether local or net or both)

both, impossible to keep local uptodate, however you may not always be
connected to the net either.

> * Searching over the net _can_ be quite slow so consider local
> index etc (updated from net) ?
see above
> * 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' !?)

and this is where the licensing issues come up, having several licenses
for different docs on the same site would be nothing short of insane
 
> * Docs/index etc would potentially be available on CDROM.
> Need to bear this in mind.

which could present a problem for the DB structure, we would need to
gather a group of programmers(i should be able to help) to get our own
search engine going(or interface to search engines)
 
> * Several "votes" for SGML/XML DocBook format. Others ??

I always ment to get into that stuff, anybody have a good rundown of
pros/cons of different doc formats?

> * Document history/traceability

some sort of CVS thing? a changelog or something like that?

Just a few thoughts

marc britten



This archive was generated by hypermail 2.0b3 on Tue Jan 11 2000 - 01:19:55 EST