Wade Hampton (whampton@staffnet.com)
Tue, 11 Jan 2000 09:55:45 -0500
Marc Britten wrote:
>
> 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.
Separate the license of the index and repository versus the documents.
Also, due to some licenses, the original may have to reside on an
external server (?). My 2C.
>
>
> > * 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.
We would need:
1. document description and howto
2. template
3. tool set
4. GUI of some sort
5. ability to create a very short document from a simple text doc
(someone mails you a text doc for inclusion or for simple technical
notes)
>
> > 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.
Agree -- do a draft standard, issue for RFC to all the other groups,
include all and state clearly that the purpose is to **facilitate**
good, standard open source docs, not to step on **anyone's** toes.
>
> > * 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?
sgml tools provides source->ps, source->html, source->text.... The
format
chosen should provide a similar set. And with source->ps, you can
also use ps2pdf to get a pdf document.
>
> > * 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.
And check out the work by the Linux KB.
>
> > * 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.
Agree -- waiting is not a good idea. We need to get the ball
rolling now.
>
> > * 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.
Yep. The main focus of this group should be to facilitate the
standards, organization, creation, and maintenance of good docs.
>
> > * 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.
Possibly local with an index. The index could be virtualized so if
a newer is on the WWW, the version from the WWW would be used when
on the net? Also the ability to update the local copy (and the ability
for the master local to be on CD-ROM with the update on the disk?).
>
> > * 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
Yep but it is reality.
>
> > * 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)
Plus tool for the local host (browser based?).
Step 1 (see my previous mail) would be to define the requirements,
step 2 the formats. Once those are done, then you can work on
implementing tools for the formats (generation, indexing, searching,
user I/F, etc.).
>
> > * 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?
Some comments:
1. There are a lot of legacy formats or formats for other purposes
(e.g., man pages) that would have to be included.
2. The standard should have 1 master format, but allow for
several other subsidary formats such as html only, URL reference
only (e.g., out of someone else's database), text, GNU info,
man, tex, etc.
>
> > * Document history/traceability
>
> some sort of CVS thing? a changelog or something like that?
CVS/RCS for most. The ability to roll-back changes or get
a previous version. The ability to sign important documents
and validate them (e.g., would you trust a security document
that someone else has altered?).
Cheers,
-- W. Wade, Hampton <whampton@staffnet.com>Linux is new, it's come out of nowhere, it's free. Hard to beat that price. And it's taking marketshare left and right.
--Microsoft's lawyer, in closing argument, Bristol v. Microsoft, http://www.microsoft.com/presspass/bti/07-15closing.htm
This archive was generated by hypermail 2.0b3 on Tue Jan 11 2000 - 09:57:32 EST