Salut.

Vous aurez peut-être vu ça sur LinuxFr... si oui, désolé du doublon ;)

On y parle de traduction, entre autres sujets qui nous intéressent 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

At <a href="http://www.ora.com/frank/oscon_summit.html" target="_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.

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.

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]

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]

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.

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.

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,

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".

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)

• Introduction : Licenses

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.

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.

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.

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.

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.

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.

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.

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="http://www.oreilly.com/catalog/awkprog/" target="_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.

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.

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.

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.

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.

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.

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.

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.

• Recruiting Volunteers

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".

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.

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.

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.

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.

On the FreeBSD side, Nik Clayton said they try to make it so the tools install properly by issuing one command.

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.

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.

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,

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.

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.

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.

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.

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.

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.

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.

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.

• Interroperability Between Projects

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.

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.

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.

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.

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.

• Identifying the Tools

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.

Norm and Michael pulled together a list of the concerns that everyone in the room seemed to have regarding tools used for creating documentation and DocBook: Small projects Linking Editors XML vs SGML (namespaces, XInclude, etc.) Metadata Schemas Translation Customization layer

• Editors

• XAE: XML Authoring Environment for Emacs.

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.

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)

• Morphon: A GUI text editor. (more detail needed)

• EPCedit: SGML editor (not OS)

• XML vs SGML

• Namespaces are a way of associating prefixes with a URI. For example:

xmlsn:ers="http://www.oreilly.com/"

Which gets used as:

&lt;er:foo&gt;...&lt;/&gt;

• Schemas

We're basically stuck in a holding pattern right now until some other piece of technology comes along.

DTD validation will have to be replaced by Schema-of-your-choice validation.

• Linking and small projects<

XPointer seems to be the emerging answer to id:idref.

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.

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.

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.

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.

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

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.

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:

       Edit/Convert
         Document
            |
            |
         DocBook
  +_____/  /\
  |       /  \
  |---XSL(T)  DSSSL (C++)
 /      /        \
/      /          \HTML

/ HTML/ \RTF / FO/ \TeX / | | some | Jade TeX thing /|\ else / | \ / | \ FOP | ? Passive TeX

Legend:

FO="Formatting Objects," which is an XML syntax

Norm said that he has written a Java implementation for XSLT and is looking for someone to write one in C.

Cataloging and Packaging are also issues. Simon says: "It's not sexy for some reason."

Norm Walsh: "SGML is dead. XML is the way we need to go."

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.

If we all agree on the basic toolset to get to PDF, then this is possible. db2latex on <a href="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.

• Developing an OMF Database

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.

• Translating Documentation

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.

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.

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.

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.

• Whats need to be done

The meeting wrapped up with the attendees giving their feedback about what they thought was good or accomplished at the meeting:

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 tools 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 DocBook DTD Stale documentation on the Internet; should there be a license that restricts people from adding ads to the pages or forcing people to maintain updated 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?

• Conclusion

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.

It was also clear that the 2 first documentation meetings, hosted by O'Reilly in California, prevented some europeans attendees to come.

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.