franzoni@edisons.it
Mon, 17 Jan 2000 11:56:55 +0100 (CET)
On Thu, 13 Jan 2000, Paul M. Foster wrote:
Before all, I apologize for my English. I really appreciated Deb's long
post about carts and horses :-) and the following discussion, and I think
that she is right when she says that first of all a representative of each
mayor group should be contacted. I do also think that those
representatives could be of real help in writing the project specs, so we
probably should only write a draft of what this project wants to do (such
as "solve issues of open source documentation") and wait for them to
contribute before making choices.
As for which projects to contact, I would put in also the many translation
projects in other languages: in my experience (I can speak for the Italian
one) there are many good docs written in non-english languages which could
easily be translated in English and added to the knowledge base. Moreover,
having a central repository/access point for documentation in english and
non-english languages would be a very important thing for non-english
people (it would be easier to get local doc - if exists - and switch to
english doc if it doesn't).
This said, here are my 2c ramblings :-)
> Now, what's wrong with open source documentation?
I think we should think separately of documentation on the web and system
documentation, even if it is often the same material. All system docs can
be put on the web, but not the opposite (hehe, even if you have very big
hard disks :-) so problems like "docs are not newbie-oriented" are very
true for system docs and not so true for online docs.
> 1) It's difficult to access from a single point/program.
this is both true for on-line doc and for system docs. For on-line docs
the solution could be a central repository/search engine, for system docs
it's up the the distributions.
> 2) Unless you search in very specific ways, it is difficult to find what
> you're looking for. I.e. it's not indexed well or at all.
>
> 3) The docs are written for hackers. I don't know what we can do about
> that, but it is a problem. Perhaps our ultimate purpose would need to
> include a proviso that we do not meddle with semantic content of docs.
this is mostly true for system docs (i.e. man pages, info doc) but not for
online docs. We can't do much about that, but probably just a
cathegorization like "newbie", "medium", "advanced" can be of help.
> 4) The source format of the documentation may not always lend itself to
> output in other formats than the original.
This is a difficult problem to approach. Authors are a rare thing, and I
don't think it's a wise thing to try to force them to do anything (i.e.
something like compelling them to use a predefined language). Another
issue is that the original document format could not be good for indexing
or for other things. And then, sometimes when the document is also
sold in printed form, the editor wants it to be in only one format (mostly
html) which is not easily transformed.
5. It is often very difficult to know if the version you have is the
latest one or not (i.e. some howtos have been moved from one project to
another)
6. It is often very difficult to know if there are translations of the
document into other languages.
7. Licenses. This is another huge issue. Is it wise to try to put
everything under only one license?
8. Integration of Linux docs with non-linux ones, for example about
networking or other unix flavors. We should probably write down some specs
about which documentation to include in the project and which not, or we
will end up with someone asking if they can submit an howto on printing
under windows 95 (been there, done that - and ours is a Linux-only project
:-)
just my 2c
Eugenia
This archive was generated by hypermail 2.0b3 on Mon Jan 17 2000 - 06:46:26 EST