Linux Congress Documentation and Localization Workshop

Monday, 2 October 2000

Held on 23rd and 24th September, 2000

Report by Eric Bischoff ebisch@cybercable.tm.fr

Documents:

1. Summary
2. Agenda
3. Decided action items
4. Presentations
5. KDE Editorial Team Status Report

1. Summary

• the German Unix Users Group for the initiative of this Workshop as part of the 7th Linux Kongress
• the German Ministry of Education and Scientific Research for the funding
• the Friedrich-Alexander University of Erlangen-N�rnberg for the hosting
• the companies Caldera Deutschland and SuSE GmbH for the logistics.

• meet
• define policies and priorities
• coordinate work
• solve technical issues.

• Thomas Diehl - applications translation coordination
• Eric Bischoff - documentation coordination
• Frederik Fouvry - DocBook technical issues
• Stephan Kulow - servers and packaging
• Lauri Watts - documentation editorial team
• Karl Backstr�m - Swedish team
• Juraj Bednar - Slovak team
• G�rkem �etin - Turkish team
• Fran�ois-Xavier Duranceau - French team
• Matthias Kiefer - German team
• Pedro Morais - Portuguese team
• Denis Pershine - Russian team
• Elvis Pfutzenreuter - Portuguese of Brazil team
• Andrea Rizzi - Italian team
• Victor Romero - Spanish team
• Hasso Tepper - Estonian team
• Lukas Tinkl - Czech Team
• Andrej Vernekar - Slovenian team

• applications translation
• documentation writing
• documentation translation
• web servers translation
• coordination with other projects.

2. Agenda

Saturday 23/09/00

Sunday 24/09/00

3. Decided action items

3.1 - Translation teams

3.2 - Developpers

3.3 - DocBook team

3.4 - Editorial team

• in khelpcenter pages
• on http://bugs.kde.org (perharps use the hypotetical new mailing list for doc writers?)

3.5 - Web server maintainers

3.6 - Troll Tech company

4. Presentations

4.1 - Report from the translation teams

4.2 - Coordination with other projects

• have metainformation for documentation (Dublin Core project), integrated to DocBook or not, like we already have Linux Standard Modules (LSMs).
• Standardize the help browser (Dewey Project)
• Standardize the DocBook tools, in conjunction with the DocBook-tools project at sourceware (Mark Galassi), the SGML-tools Lite project (Cees De Groot) and Linux Standard Base.
• Watch the Li18nux project on infrastructure for localization
• Help the conglomerate project to write a DocBook editor, maybe have own own someday

4.3 - Doc writers

4.4 - Web server

4.5 - Context information in po files

• English only has singular and plural so two msgids are enough:

    "Are you sure you want to delete this file"
    "Are you sure you want to delete those %1 files"
  

  but the termination of the names and adjectives depend on the last digit of the number displayed at %1 placeholder.
• The prepositions for days of the week, and months depend on the day or month that follows, while "on" and "in" are enough in English.
• Etc

4.6 - kbabel

• modules for external programs
• support for qml language in po files
• dictionaries and anti-dictionaries
• use other existing po files to start translation of a new one
• context information on surrounding lines

4.7 - Screenshots

4.8 - FDL licence

• title page
• cover text (front and back)
• main section (normal thing)
• secondary sections (off topic)
• invariant sections (might not be changed)

4.9 - Style sheets for documentation

• the fixed texts
• the typographical conventions
• the order of words
• ...

4.10 - DocBook

4.11 - Glossaries

5. KDE Editorial Team Status Report

5.1 Background (where we started from):

5.2 Accomplishments:

1. The infrastructure is in place, and coordinators (Lauri and Mike) have enough background concerning the technical aspects of the KDE project to be efficient.
2. The editorial team has a website with information on writting, marking up, and submitting documentation, FAQ's, help for installing snapshots, and a status page so anyone can see who is working on which applications documentatin, and its status.
3. The editorial team has completed (in time for KDE 2.0):

   kdeadmin   66% (4 of 6)
   kdebase  75% (9 of 12)
   kdegames 36% (8 of 22)
   kdegraphics 20 % (1 of 5)
   kdemultimedia 50% (3 of 6)
   kdenetwork 20% (2 of 8)
   kdepim 50% (1 of 2)
   kdeutils 71% (10 of 14)
   TOTAL 38 pieces
   

   In order to qualify for this list, all of these documents must be: 1) updated for KDE 2.0; 2) Current (to the best of our knowledge), 3) Installed correctly, and correctly "attached" to the help features of the application; 4) Correctly marked up for docbook 3.1.
4. The editorial team is currently working on 19 additional applications, which are at various stages of development.
5. Every application in KDE 2.0 correctly loads a help page (even if documentation has not been completed). The most complete and current version of documentation is made available, and if the documentation has not been written at all, a small help page pointing users to helpful links is loaded in its place.
6. All documentation for unreleased/discontinued applications has been moved/removed from the CVS.
7. All docbook files, compile without errors when using jade and the customized KDE files.
8. Several documenters spent many weeks adding "What is" help to kcontrol modules, and applications.

5.3 Way of working

5.4 The stated mission of the editorial team is to:

1. Compose new documentation and update previous versions of documentation for KDE applications.
2. Assist translation teams whenever possible so that they may effectively and accurately translate this documentation.
3. Work to ensure that all English documentation is correct and complete with regards to docbook markup.
4. Recruit new people to write documentation.

5.5 New documentation is currently written as follows:

1. New documenters contact Mike, who answers questions, asks them to read the FAQ and guides to writing documentation on the web page.
2. Documenter downloads a current snapshot and installs it (questions/problems are referred to Mike who answers them if he can, if not, the questions are referred to kde-devel).
3. Once installed, the documenters and Mike work together to choose an application for them to write about.
4. The documenter contacts the primary developer on the application.
5. The editorial team status page is marked "Started", to signify that someone is working on that documentation.
6. The documenter writes the documentation either in plain ASCII, or docboook, depending on their level of knowledge of docbook. If there is previous documentation for an application, then the documenter uses the "old" documentation as a starting point for the new documentation.
7. After the documenter feels they have finished their documentation, they email the document to either Lauri or Mike (who forwards it immediately to Lauri).
8. Lauri reviews the submitted documentation for: Correct use of docbook markup, correct grammer/punctuation, accuracy, completeness, and overall organization. Lauri works with the documenter to correct any problems.
9. Lauri sends the corrected documentation to Mike, who verifies the docbook is error free, and briefly checks it for obvious errors. Mike then submits the documentation to the CVS, updates the two status pages, updates the credits page, and informs the documenter that the documentation has been sent to the CVS.
10. The next time the documenter updates their source code, they check over the documentation to make sure everything is being installed correctly, and that there are no errors.
11. The documenter begins at step 3 with the next application.

5.6 Problems encountered: (In no particular order)

1. Docbook tools are very difficult for most people to install. Even though this is not a requirement for documenters, approximatly half of the documenters insist on installing this program so that they can check their work, see how it looks, etc. More than 10 potential documenters have been lost from the frustration of installing docbook tools. I know that Eric has been working on simplifying this, and the frustration that I have noted, has been less over the past couple of months, though occasional discussions of this subject do occur on different mailing lists.
2. Early volunteers often had many problems installing KDE, since it was still alpha code. Now that KDE is more stable and robust, volunteers have an easier time installing and working with KDE, so fewer people are leaving.
3. It has been very difficult to determine which applications would be part of which packages (or had been discontinued entirely). Changes are made to the contents of packages, and to my knowledge, there is no central location to determine what applications are in which packages and no official announcements are made.
4. The exact cutoff for submission of new documentation is not well defined in any of the recent release schedules.
5. Developers fail to return email messages from documenters or documentation coordinators regarding specific and usually technical questions. This has the obvious effect of delaying documentation, it also has the more signifigant effect of making documenters feel unappreciated and "like second class citizens".
6. Developers will change the user interface of an application without telling documenters, without any apparent announcements to help documenters out, and often after "feature freezes". (On September 16, Waldo Bastian has implemented an addition to the CVS, so that the documentation team is notified whenever developers include the phrase "GUI" in their CVS commits. It is too early to determine if this is effective yet, or not).
7. Markup choices have been a moving target for us, since many of the details were worked out as we went along and since Lauri and I were still learning the in's and outs of docbook as it relates to KDE.
8. Documenters have left the project without telling us.
9. Documentation that is written in a foreign language must be translated into English before other translations can translate it, but this Language X --> English translation is very slow.
10. A documenter was split off to help "Proofread the English of the user inteface." After I sent him to the kde-i18n-doc mailing list, and told the people who had been requesting this person, no one ever helped him get started with the project, so he sat waiting for over 2 months for some help. This has resulted in 1) A docuemnter not helping the documentation team because he felt uneeded; 2) There are many minor problems with the messages of applications, that could have been fixed prior to a user interface freeze.
11. Certain consistency issues have not been successfully implemented. This is usually due to Lauri or Mike not recognizing the need for consistancy in this specific situation.
12. Snapshot and graphics files locations and requirements were changed part way through documentation. The required that all snapshots be updated, and that many large application documents be edited. This has not been completed.
13. Some documentation was written without informing the KDE documentation team. This resulted in two instances where work on documentation was discarded because of two different versions of documentation for an application.
14. When applications were moved among the kde packages (into another package, to kdenonbeta, or deleted entirely), the documentation was often left in its original place. This is really a minor problem, and if I am informed of package changes, then I can make sure the documentation is where it belongs.

5.7 Writing new documentation

5.8 To summarized the status of the documentation project:

5.9 What works and what doesn't.

5.9.1 Works

5.9.2 Not working well (and some possible solutions)

Problem #1

Problem #2

1. Current Release schedule. An excellent release schedule was posted (http://developer.kde.org/development-versions/release-schedule.html), which clearly spelled out each step in the release cycle, who was responsible for that step, and what was completed. Unfortunately, this page was no longer updated a few weeks later, and remains more than 45 days out of date.
2. Applications have been removed from the KDE release. It has been difficult to ascertain which applications will be included in the KDE 2.0 release. Obviously this is a moving target, but no announcements were made to any kde mailing lists that I could find when such an event happened.
3. Which applications are part of which package. This has been equally challenging to the documenters because applications are moved between packages, or into the kdenonbeta package, without any official announcement.
4. Who maintains the kde packages? Who maintains the applications?. It is often difficult to determine who you should talk to if you have a question about a package or an application. Sometimes, you can use the Help-> About option, sometimes the AUTHORS file will help, sometimes, you can review the CVS logs to determine who is making the major changes, but sometimes you can not determine who it should be.

Problem #3

1. The resulting documentation may be incomplete or inaccurate.
2. The documenter feels like a second class citizen to the developer she is trying to help.
3. Documentation updates are delayed.
4. Applications do not get documentation in time for release because their exact status cannot be verified.

Problem #4