From oberger@april.org Sat Aug 25 13:19:23 2001
From: Olivier Berger <oberger@april.org>
To: traduc@traduc.org
Subject: [Traduc] Rapport du 2nd Annual Documentation Summit
Date: Sat, 25 Aug 2001 13:13:20 +0200
Message-ID: <3B878850.4E30BFAE@april.org>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="===============0650160409736024914=="

--===============0650160409736024914==
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable

Salut.

Vous aurez peut-=C3=AAtre vu =C3=A7a sur LinuxFr... si oui, d=C3=A9sol=C3=A9 =
du doublon ;)

On y parle de traduction, entre autres sujets qui nous int=C3=A9ressent ces
temps-ci...

Copie de http://externe.net/documents/PR :

>                     2nd Annual Documentation Summit
>                        Sheraton Hotel and Marina
>                            San Diego, CA, USA
>                              July  22, 2001
>                 Document compiled by :  Guylhem P. Aznar
>                   From notes taken by : Joy E. Yokley
>             With additional informations from :  Norm Wash, Chuck
> Toporek, Laurie Petrycki, Simon St.Laurent, Guylhem P. Aznar, Eric
> Raymond and Betsy Waliszewski
>=20
> At <a href=3D"http://www.ora.com/frank/oscon_summit.html"
> target=3D"_blank">last year's first Open Source conference</a>, a group of
> folks interested in documentation efforts from various Open or Free
> software groups was brough together. The goal was to get each of these
> groups talking with each other to find out if there was a way to
> standardize what they were doing to write and distribute their
> documentation.
>=20
> The purpose of the Documentation Summit was to evaluate the current state
> of open-source documentation and documentation technologies and to develop
> initiatives and cooperation between the various projects. The Summit took
> place prior to the O'Reilly Open Source Convention.
>=20
> Participation in the Summit was by invitation only. The following
> representatives attended the Summit:
>   Guylhem P. Aznar [chairman - LDP]
>   Michael Smith [chairman - DocBook Technical Committee, XML DocBook]
>=20
>   Chuck Toporek, [O'Reilly]
>   Simon St. Laurent, [O'Reilly]
>   Eric Bishoff [KDE, Caldera]
>   Nik Clayton [FreeBSD]
>   Bradley Kuhn [Free Software Foundation]
>   Miles Efron [Metalab/ibiblio]
>   Johnray Fuller [Red Hat]
>   Mark Galassi [Los Alamos National Laboratory]
>   Ron Hayden [Apple Computer]
>   Jirka Kosek [DocBook-tools]
>   David Lawyer [LDP]
>   Bob McIlvride [Cogent]
>   Laurie Petrycki [O'Reilly]
>   Eric S. Raymond [LDP]
>   Bob Stayton [Caldera]
>   Murray Stokely [FreeBSD, WindRiver]
>   Betsy Waliszewski [O'Reilly]
>   Norman Walsh [Sun,DocBook Technical Committee]
>   Joy E. Yokley [IBM, LDP]
>=20
> The following goals were identified in a brainstorming session :
>   Variety of issues related to discussions with authors who are writing
>   documentation.
>   Understanding of editorial issues
>   Cross referencing between documents
>   "Fundamental infrastructure"; changes like XML
>   URNs, repositories for documentation
>   Ease of use and distribution
>   XSLT infrastructure
>   Desktop environments for documentation (native browsing)
>   Installation-wide indexing, automatic installation with RPMs
>   Contextual help ("Press F1" like)
>   Project coordination
>   Metadata, Dublin core
>   Schema support
>   XML features (XInclude, packaging, etc.)
>   Translation in DocBook
>   Indicating changes to docs
>   Licensing -- how to protect investment in editorial
>   Interroperability between projects for resource discovery issues
> across repositories.
>   Math (and when can scientists stop using LaTeX)
>   Broad issues for making the documentation more usable
>   Finding writers and getting people to contribute to documentation
>   Encouraging new authors to use LinuxDoc instead of DocBook (easier to use)
>   Coordination of big projects
>   What are the weak places in the tool chain
>   Documenation formats (Texinfo, LinuxDoc, DocBook)
>   Converting legacy formats (such as texinfo, troff, etc.) to DocBook
>   DocBook for small projects
>   DocBook to man (nroff)
>   A GUI DocBook editor is desparately needed.
>   Keeping documentation up-to-date on the Internet
>   Other meetings
>   Scrollkeeper
>   Schema extensions
>   Standardizing metadata
>   Task of deciding about what to do with Schema support
>   The question of XML features. XML is at a crossroads right now, and
> Norm's anticipating what or when to stop SGML support in DocBook to
> support things like XLink and Namespaces.
>=20
> Among last year realisations are :
>   Beginning of LDP HOWTOs conversion from LinuxDoc to DocBook (60%
> achieved)
>   Scrollkeeper (http://scrollkeeper.sourceforge.net), a free electronic
> cataloging system for documentation which provides a simple API to allow
> help browsers to find, sort, and search the document catalog.
>   Getox (http://idx-getox.idealx.org), an independant initiative, was
> also mentionned.
>=20
> One point that was brought up by Eric Raymond was that, at last year's
> DocSummit, all of the groups settled on DocBook SGML/XML as the standard
> form of producin g documentation. Therefore, the recommendation made by
> David Lawyer to encourage new authors to use LinuxDoc instead of DocBook
> wasn't really a "goal" that we would move forward with. Yet some
> interest remains in this easy to go format, once also used by the BSD
> documentation, if it could be made easily convertible to DocBook,
>=20
> The following sections detail the topics that were addressed at the meeting
> as well as the outcome of those discussions, after an introduction
> speech given by David Lawyer and a sum up of the North Carolina LDP
> meeting by Guylhem Aznar, on the licenses and format "ratholes".
>=20
> This term was later defined by Eric S. Raymond, as a discussion for
> which no conclusion can be hoped, each argument being valid but
> incompatible with the next one (Eric, please correct)
>=20
> * Introduction : Licenses
>=20
> A free copyrighted document (doc) must have a license that gives anyone
> the right to freely and responsibly do the following: copy, distribute,
> display and modify. This latest point was subject of discussions
> (concerns on Trojan documentation were expressed) and no agreement could
> be reached on the right to publish and commercially exploit free
> documentation.
>=20
> Because there are multiple licenses available for documentation to be
> published as "free" or open source, the LDP (Linux Documentation Project)
> issues of re-licensing and combining documents has become a problem. The
> area where this creates the most concern is with out-of-date documentation
> when the author cannot be located to make changes to the documentation.
>=20
> At issue for David Lawyer was that some Internet sites had up older, out
> of date, documents, or that the site had banner ads on the same page
> with what should be "free" documentation. suggested making it a
> requirement that documentation have a date (copyright or otherwise)
> attached to the doc so people who access and read the doc know that it's
> current. The general consensus of those attending the DocSummit was that
> there would be no way to police other sites, or to know what has been
> cached on someones machine or intranet.
>=20
> While out of date documentation is also a problem, readers are already
> comfortable with it. Some people suggested including in the license some
> obligation to provide the latests version or at least a way to get it.
>=20
> But readers look at copyright dates, etc. Attempting to resolve this by
> licensing would interfere with web caching and produce other problems.
> It was concluded that this kind of need should be fixed at format level,
> emphasing on the creation date, rather than at the license level.
>=20
> Because the current licenses do not allow the LDP to take over the
> documentation and its management; there is a concern that documents may
> appear to be current when they are not. There is also the concern that
> documents remain on the LDP site for longer than they are relevant. While
> the review effort began at the LDP will take care of the latter issue.
>=20
> Also, because of the multiple licenses that documents are published under,
> (most popular are FDL, OCL, OPL v1, OPL v2, BSDDL, LDPL) there is no way
> to combine documents that have similar topics into one document or into
> a canonical source for that topic. The group recognized the difficulties
> this leads to but felt that there was no way that they could endorse or
> mandate a particular license.
>=20
> Mark Galassi said that he was glad to see that O'Reilly was working on
> publishing "Free" documentation, but felt that we were doing something
> of a disservice by promoting the "Open Publication License." Chuck
> Toporek responded and noted that O'Reilly isn't necessarily "promoting"
> the OPL; when in fact, O'Reilly pretty much leaves it up to the author
> to decide which license they would like to use. If an author comes to
> O'Reilly with a proposal on a technology that we would like to publish a
> book for, and the author wants to it published under either the OPL or
> the FDL, we will. For example, two books that have recently been
> released under the FDL are <a
> href=3D"http://www.oreilly.com/catalog/awkprog/"
> target=3D"_blank"><i>Effective awk Programming, Third Edition,</i></a> and
> <i>Linux Device Drivers, Second Edition.</i> And Norm Walsh announced
> that the second edition of <i>DocBook: The Definitive Guide</i> will be
> published by O'Reilly under the FDL.
> Bradley Kuhn reminded that some authors complained that this choiced was
> never presented to them, and they had to specifically ask to use the
> FDL.
>=20
> There will always be proprietary and free/open documentation. A truly
> proprietary license is where the publisher retains the rights for print
> and electronic distribution of a book. However, a "Free" license is
> intended to allow the doc to be freely distributed, in print and
> electronically, without any sort of restriction. An "Open" license
> restricts the commercial use of the document.
>=20
> Later in the day the discussion turned back toward documentation licenses,
> but this time Bradley Kuhn led the discussion of the FDL (Free Software
> Foundation open-source version) license. This license allows for multiple
> publications of the same text by multiple publishers, providing that the
> back and front covers are preserved. There are benefits and risks with this
> kind of license. The first drawback is the need to include a full
> license with each licensed document (no linking or referencing), which
> could mean the BSD documentation license, the former LDP license or the
> OPL version 1 without options a or b licenses would be better choices
> for short documents, even if the LDPL is now deprecated.
>=20
> On one hand, readers benefit because there isn't a monopoly on the text.
> The text could be published in multiple languages through multiple
> publishers. The down-side to this type of license is that the author
> would not receive remuneration for the additional publications, nor
> would O'Reilly receive any funds. Any rogue publisher could just take a
> book written by O'Reilly and reprint it for its own benefit.
>=20
> The problem is especially present with documentation, which unlike
> software has a significant distribution and production costs, for it is
> more popular in its physical "printed" than it a screen "viewable"
> format.
>=20
> Like the other license issue, the group did not feel that they could
> privilege this license over existing licenses. Therefore, the choice of
> license will remain an author decision.
>=20
> The solution chosen by the LDP was to define the basic requirements a
> license must follow to qualify as "free" - yet this solution only fix
> the "diversity" problem, leaving the relicensing problem.
>=20
> A possible solution for the relicensing problem could be unifying the
> licenses, adding relicensing clause to the most popular licenses or
> transferring ownership of the documents to a non-profit 3rd party
> trusted to relicense the document should this kind of problem occur.
>=20
> * Recruiting Volunteers
>=20
> Eric Bischoff read a communique from the documentation manager regarding
> the release of KDE2 and the documentation associated with it :
> "We're all writing documentation, but the hard part is to get someone to
> write good documentation".
>=20
> Jonray pointed out that one problem with writing documentation is that
> the writer opens themselves up to being flamed or criticized if someone
> doesn't like what they've written. It's hard to keep volunteers around
> if they're getting banged on.
>=20
> Mark brought up the point that some people who write documentation can
> be lead down the path of writing code. He also commented on how amazed
> he was at the speed and quality of the people who are working on foriegn
> language translations.
>=20
> Bradley Kuhn commented that part of the reason why the GNOME
> Documentation Project (GDP) has been so successful is because Dan
> Mueth's leadership and the way he encouraged and treated the writers.
>=20
> On the Darwin Project, most of the people who are interested in writing
> documentation are programmers who are wanting to write about something
> they're working on. The problem is that they have trouble getting the
> tools installed on their system, and they end up walking away.
>=20
> On the FreeBSD side, Nik Clayton said they try to make it so the tools
> install properly by issuing one command.
>=20
> The LDP reminded that its policy of 'directed anarchy' and tradition of
> freedom was still active, and that no orders or nonconsensual decisions
> were never enforced, in an effort to keep attracting authors.
>=20
> The general consensus is that there needs to be a way of lowering the
> bar in that GUI tools are needed for people to author and generate
> DocBook, and then transfrom that into some other format, such as
> PostScript, HTML, PDF, or just raw text.
>=20
> While some kind of hierarchy (KDE case) may help in providing a uniform
> documentation, anarchy (LDP - GDP) can be controlled to provide more and
> more documentation. After an intense discussion between the LDP members
> advocating freedom and the KDE members advocating order, it was
> generally agreed that each project had its own rules and inner
> functionning, and that we should not try to criticize the way others
> projects works,
>=20
> One of the concerns shared by all organizations represented at the Summit
> was how to recruit and maintain volunteer authors and editors for the
> projects. There are primarily two real hurdles for recruiting documentation
> volunteers: 1) the tools are too hard to learn and use without having
> someone knowledgeable to give instructions on installing and using them, 2)
> potential authors see documentation as secondary to developing software,
> with very few possible advantages for either their online popularity or
> their future carreer.
>=20
> One of the reasons that it is hard to get volunteers to work on open-source
> documentation is the learning curve associated with the tools. It is hard
> to get authors and editors excited about using Emacs when they are coming
> from a Windows editing environment. The general consensus among Summit
> participants was that there needs to be a simpler editing tool that allows
> for on-the-fly validation of documents. This easier-to-use editing
> environment would also be easier to set-up than the current method of
> downloading and unzipping all the right files to all the correct places.
>=20
> Some of the participants believed that a more pared-down version of DocBook
> was needed to get authors and editors who had never used semantic markup
> languages comfortable working in SGML or XML. Norman Walsh (a principle
> creator of the DocBook DTD) said that he did not know if DocBook would
> scale below one hundred tags; therefore, he wasn't sure that he would be
> able to create a pared-down version of DocBook. David Lawyer from the LDP
> suggested that the older DTD, linuxdoc, would be an excellent alternative
> because of its simplicity, for some short documents or new authors. The
> remaining Summit participants dismissed linuxdoc as an option because of
> its failure to meet DocBook standards and the subsequent difficulties
> automating its conversion into DocBook. The LDP was also criticized for
> its continued use of linuxdoc. Participants at the conference felt very
> strongly that continuing to accept documentation in linuxdoc was a real
> mistake for the LDP. However, current president of the LDP, Guylhem
> Aznar refused to commit the LDP to transforming all documents to DocBook
> in the upcoming year. He feels that as an open-source organization there
> needs to be consensus within the LDP before making a blanket statement
> about what will and will not be accepted. He did commit the LDP to
> adopting DocBook but said that conversions to DocBook would take place
> voluntarily for 100% of the documents currently housed on
> the LDP before the LDP would begin mandated DocBook for all new
> submissions : lots of people are intimidated by the tools needed to do
> XML. One solution is to make sure the tools that need to be installed
> are well documented and easy to install. There is currently no easy to
> use free software XML suite for linux.
>=20
> In order to address the issues of easier to use tools, it was agreed to
> move the discussion to the documentation leaders email list that was set up
> for conference participants. This list will be archived for others to read,
> but only those subscribed will be able to participate in the discussion.
> Summit participants volunteered to test editing tools currently in
> development in order to identify what projects were most beneficial and
> report back to the group. The goal is to be able to commit some personnel
> resources to the most promising tool projects.
>=20
> The second area where participants saw problems recruiting authors was
> within the developer community. Participants from the various organizations
> did not see enough developers volunteering to write documentation. This
> failure could be due to a couple of different factors. Some participants
> believe that developers and system administrators do not write
> documentation because they do not realize how important it is. Developers
> and system administrators  believe that someone else out there is writing
> the documentation and that all developers and system administrators don't
> need to publicize their fixes.  Participants at the conference also voiced
> the belief that many developers and system administrators feel that writing
> documentation is beneath them. They would rather be programming or fixing
> problems instead of writing about the code they developed or the steps to
> their solutions and making these solutions available to the public. In
> order to address these areas, participants at the Summit agreed to begin
> actively speaking out about documentation and how much the community needs
> documentation. The LDP has been involved since april 2000 in active voluteer
> recruitment in Conferences and conventions. They were identified as
> great places to begin educating potential authors about the value of
> documentation.
>=20
> Also, Summit participants have begun a campaign to try to contact
> developers who do write documentation to, in turn, contact ten other
> developers and convince them to write open-source documentation - since
> documentation is a gateway to beginning to write code, there will always
> be a lack of documentation authors in the free software community.
>=20
> Another problem is lots of documentation is written informally - in
> email message, on usenet, in some webpages only accessible though search
> engine. Some linux users, for exemple in the third world, do not have
> permanant online access.
>=20
> Certainly, money helps. How else? Documentation "itch scratching" isn't as
> rewarding as writing code. It doesn't have the same prestige. But since
> Many people entering the Libre software community now (as opposed to 15
> years ago) aren't programmers, we should try to leverage these people
> who may be good writers.
>=20
> * Interroperability Between Projects
>=20
> Eric Bischoff said that the KDE group has been working with the GDP on
> trying to figure out what tools are best. One suggestion he had was that
> knowing the right people to write the documentation certainly helps.
>=20
> The LDP explained it started to integrate small projects in its
> "federal" organisation, where each project is fully independant, but
> ressources are shared. LinuxDoc tools and format are currently
> maintained and new DocBook and XML tools are in project.
>=20
> Discussion on DocBook Extensions: Should we all agree to stop adding
> extensions and to submit them to the DocBook steering committee? Norm
> said that he would like to see extensions submitted to the DocBook
> Steering Committee first before they are implemented.
>=20
> Eric seconded that by suggesting to everyone that they stick to the
> DocBook DTD, but when you have or need an extension, send them to Norm.
>=20
> Norm said that he has been thinking about adding something to the
> DocBook site that lists the extentions to DocBook so people can download
> and use them if they want/need to.
>=20
> * Identifying the Tools
>=20
> When the topic of tools was addressed most of the participants were in
> agreement on several issues:  1) DocBook is the standard DTD, 2) SGML is
> dying while XML is thriving, 3) good, free tools for writing documentation
> are not available. While the first two items did not elicit a great deal of
> discussion, the third item was a large topic.
>=20
> Norm and Michael pulled together a list of the concerns that everyone in th=
e room seemed to have regarding tools used for creating documentation and Doc=
Book:
>   Small projects
>   Linking
>   Editors
>   XML vs SGML (namespaces, XInclude, etc.)
>   Metadata
>   Schemas
>   Translation
>   Customization layer
>=20
> - Editors
>=20
>  - XAE: XML Authoring Environment for Emacs.
>=20
> What's needed in a GUI editor:
>   Seeing the tags available to you at the moment.
>   Tying into XSLT to take the document you've just created and transform
>   it into whatever form you need.
>=20
> Mark said that a "structured view" of SGML in Emacs was pretty useful.
> He said another useful tool is Adobe's Frame+SGML, but it has its own
> inherent problems (such as it doesn't always work properly with the
> DocBook DTD)
>=20
>  - Morphon: A GUI text editor. (more detail needed)
>  - EPCedit: SGML editor (not OS)
>=20
> - XML vs SGML
>=20
>  - Namespaces are a way of associating prefixes with a URI. For example:
>=20
> xmlsn:ers=3D"http://www.oreilly.com/"
>=20
> Which gets used as:
>=20
> &lt;er:foo&gt;...&lt;/&gt;
>=20
>  - Schemas
>=20
> We're basically stuck in a holding pattern right now until some other piece=
 of technology comes along.
>=20
> DTD validation will have to be replaced by Schema-of-your-choice validation.
>=20
>  - Linking and small projects<
>=20
> XPointer seems to be the emerging answer to id:idref.
>=20
> One of the most frustrating areas faced by open-source documentation
> developers is the lack of tools to work on documentation. The general
> consensus is that there are no free, easy to use, open-source tools to edit
> and deliver open-source documentation. Even if you are able to get the
> documentation into DocBook, you still run into a tremendous amount of
> difficulty implementing style sheets and converting the source to an output
> document. The difficulty with output is even greater when trying to
> generate a printable version of the document.
>=20
> There are primarily two types of stylesheets that can be used to format
> source output: DSSSL and XSL.  DSSSL stylsheets use a Scheme-based
> language that is difficult for non CS-majors to program with.  Jade and
> OpenJade are C++ implementations of the DSSSL standard.
>=20
> DSSSL stylesheets can output HTML and RTF formats without much
> difficulty once the stylesheets are configured. However, if the output
> needs to be in PDF, the output of the DSSSL must first be run through TeX
> and JadeTeX. JadeTex is not particularly stable and falters quite often.
>=20
> XSL, sometimes called XSL(T), stylesheets are easy to manipulate and
> configure. They produce HTML output with no problems. However, there is
> currently no other dependable output. Along with HTML, XSL conversions will
> generate an FO (formatted object). As of the Summit there is no dependable
> way to map the FO to PDF. Several projects are working on this system, but
> none of them seem to be making rapid progress. This failure to be able to
> produce PDF is a real downfall for organizations that need to generate
> printable forms of documentation.
>=20
> To address these issues, the group agreed to begin checking into the
> organizations that are trying to build converters that make FOs into PDF.
> We agreed that this is the standard of the future, and we need to
> contribute any resources available towards reaching that goal. The LDP
> volunteered to start, coordinate and host any project which would create
> more free software tools used in documentation processing
>=20
> Interoperability is also a problem, in which speeds plays an important
> role. KDE is developing a direct DocBook browsing tool - some suggested
> that while current documentation is primarly accessed in one of the
> converted format (html, pdf, etc) from the unique DocBook or LinuxDoc
> source, directly reading DocBook source may be the way to go in the
> future. Limiting to strict subsets of DocBook would help.
>=20
> Since one common goal that every documentation project seemed to be
> struggling with was DocBook tools. Some sort of GUI tool is needed to
> make it easier for people who are writing documentation to submit their
> work in DocBook. Norm presented the following flowchart of the
> progression of a document written in DocBook:
>=20
>            Edit/Convert
>              Document
>                 |
>                 |
>              DocBook
>       +_____/  /\
>       |       /  \
>       |---XSL(T)  DSSSL (C++)
>      /      /        \
>     /      /          \HTML
>    /  HTML/            \RTF
>   /    FO/              \TeX
>  /      |                 |
> some    |                Jade TeX
> thing  /|\
> else  / | \
>      /  |  \
>   FOP   |   ?
>      Passive
>        TeX
>=20
> Legend:
>=20
> FO=3D"Formatting Objects," which is an XML syntax
>=20
> Norm said that he has written a Java implementation for XSLT and is
> looking for someone to write one in C.
>=20
> Cataloging and Packaging are also issues. Simon says: "It's not sexy for
> some reason."
>=20
> Norm Walsh: "SGML is dead. XML is the way we need to go."
>=20
> Aside from having a GUI-based DocBook authoring tool, the other major
> problems of using DocBook are printing and output. libxslt by Daniel
> Velliard is the only known C-based XSLT tool.
>=20
> If we all agree on the basic toolset to get to PDF, then this is
> possible. db2latex on <a
> href=3D"http://www.sourceforge.net/">SourceForge</a>, converts DocBook to
> LaTeX. from there, you should be able to produce PDF. Another option is
> Passive TeX, an XML parser written in the TeX macro language.
>=20
> * Developing an OMF Database
>=20
> Miles Efron from Metalab presented his work on OMF  (OpenSource Metadata
> Framework) (http://www.biblio.org/osrf/omf). The primary purpose of this
> database is to index every open-source document within a single repository.
> For this purpose, Metalab developed a set of tags for metadata in
> continuation of the Dublin Core effort (http://www.perl.org/dc). The
> Dublin Core is a standard group of metadata that can be used to classify
> information.  The LDP is already using OMF on some of its ressources.
> There are 16 elements, and most are optional. The one that was added,
> beyond DC, was the <tt>type</tt> element.  In conjunction with this
> effort, the Scrollkeeper project, brought about by last year's
> documentation summit, is maturing; its purpose is to install OMF
> metadata on the end user's machine to allow easier search for relevant
> documents. Using this system, readers would be able to search documents
> based on sixteen different search criteria instead of having to search
> through titles on an index or use a search engine for hits that are
> only close to what they are searching for. The OMF effort will index
> each document by output form (PDF, HTML, PS, etc.), not by source.
> Currently the metadata forms are ready for users to start submitting
> documentation and filling in the appropriate metadata fields for each
> document. This project will take a large number of volunteer hours to
> get a significant number of documents correctly tagged with metadata.
> However, the outcome of the project should be quite exciting.
>=20
> * Translating Documentation
>=20
> KDE representative,  Eric Bishoff overviewed the automated translation
> efforts at work within KDE. He discussed how KDE was developing a
> translation memory system much like the Windows compliant Trados software.
> The process involves breaking the text of a document into small chunks,
> stored in a database. Then a fuzzy-matching algorithm matches changes in
> the English to changes in the translation.
>=20
> When a document is authored in English and translated into another
> language, there usually isn't any problem. But where problems crop up is
> when the original document gets updated (or in the case of printed
> books, when a new edition is published), because your choices are:
>   Have the book translated all over again.
>   Run a diff on the updated file and have the translator go back to the
> translated version of the document and find the place where they need to
> change the text.
>=20
> Solution:
> KDE has a tool, kbabel, that they use for performing translations on
> po files. They also have another application called
> po2xml for use in converting po files into XML.
>=20
> He says that the work is still tedious and that many of the culturally
> based scenarios in the documents did not translate well when the
> translation software encountered them. Translation of DocBook is aided
> by the fact that the documentation is technical and so there is not a
> lot of context.The translation effort is still using a great deal of
> manpower resources, but the software is making progress. Members of the
> community were very interested in how the translation effort and
> translation software would affect documentation.  The KDE tool kbabel
> can now work with DocBook.
>=20
> * Whats need to be done
>=20
> The meeting wrapped up with the attendees giving their feedback about
> what they thought was good or accomplished at the meeting:
>=20
>   Need for GUI tools for DocBook authoring (encourage Open Source
> development of such): Conglomerate psgml getex
>   Better grasp on the licensing issues
>   Linking across metadata
>   Tools are the key, especially ScrollKeeper
>   User-friendly HTML-Help
>   Getting more people to write documentation
>   Cross-platform documentation portability (particularly with metadata)
> - getting the documentation in front of the reader
>   The need to be able to print (Formatting Objects)
>   A commitment to NOT extend DocBook
>   ESR: Commitment to start writing documentation about writing documentation
>   in DocBook
>   Guylhem: The LDP already provides many documents, including Authoring
>   HOWTO to aspiring authors
>   Nik brought up the point that the FreeBSD Documentation
>   Project has a 130+ page documentation primer and the KDE and Gnome
>   folks have excellent material as well -he thinks ESR really just didn't
>   look very hard for all of the great docs howtos out there. ;)
>   Translation tool progress
>   Diversity of approaches to managing projects
>   Look at licensing with an open mind
>   Submit proposals for conferences next year
>   Contribute to breaking down barriers: Nobody has a magic bullet on the to=
ols side. Hopefully some momentum will come through on the mailing list.
>   Should we standardize on the basic DocBook DTD without extensions.
>   RH will implement Nautilus in their 7.2 release, so that's where improved=
 metadata in documentation will be helpful to users, particularly newbies
>   Backend tools are important.
>   LinuxDoc does have problems, but maybe we need a simpler version of the D=
ocBook DTD
>   Stale documentation on the Internet; should there be a license that restr=
icts people from adding ads to the pages or forcing people to maintain update=
d versions of the doc on their site
>   Getting docs "in front of the reader"
>   Better grasp of licensing issues
>   Translation tool progress
>   Diversity of approaches to managing projects
>   Better understanding of linking
>   Submit proposals for LSM & O'Reilly Open Source Conference
>   Closer to resolution of metadata issues
>   Need GUI tools for DocBook authoring
>   Cross-platform distribution of documentation
>   Need user-friendly help system like HTMLHelp
>   Need something simpler than DocBook; perhaps LinuxDoc can become that?
>=20
> * Conclusion
>=20
> While this meeting was considered as very satisfying, it was decided
> that the problems and the implementation of the solutions should be
> followed by consequences. Therefore, the mailing list for documentation
> leaders was created, and an IRC session was scheduled after the meeting.
>=20
> It was also clear that the 2 first documentation meetings, hosted by
> O'Reilly in California, prevented some europeans attendees to come.
>=20
> Consequently, Guylhem Aznar proposed to let the LDP prepare the 3rd
> documentation meeting with help from the FSF and host it in Europe, in
> Bordeaux, France for july 2002.

--=20
Olivier BERGER - Secr=C3=A9taire de l'association APRIL=20
APRIL (http://www.april.org) - Vive python (http://www.python.org)
P=C3=A9tition contre les brevets logiciels : http://petition.eurolinux.org


--===============0650160409736024914==--