Report by Eric Bischoff <email@example.com>
The first meeting of KDE translation and documentation teams has been a success. We must thank:
KDE is an Open Source software project (www.kde.org). The purpose of the KDE Documentation and Localization Workshop was to give people involved in KDE's documentation and translation an opportunity to:
This success demonstrates that there are strong energies willing to bring Unix Operating Systems and Free Software to the citizen with a documented, easy-to-use graphical interface, in their own language. This is an approach that proprietary operating systems are unable to sustain consistently. Now that computers have come to everyday life, this is putting a threat on cultural independance of many countries with respect to American languages. On the contrary, all the people attending the workshop are committed to making computers - even using powerful Operating Systems like GNU/Linux - more easy to use for everyone.
Attending team leaders were:
The KDE project (www.kde.org) represents more than 50 languages by now and we were sorry not to be able to invite a representative for each team. We are hoping to be able to reproduce this event with other persons soon, with a special thought for Japanese, Chinese, Korean, Hebrew, Arabic, Greek, Dutch, Romanian, Hungarian, Icelandic, Hindi/Urdu and many other teams.
Persons having collaborated every day for years, either on a voluntary or on a professional basis, were happy to meet personnaly for the first time. The ambiance was nice and productive.
Covered areas of work included:
All the subjects of the agenda have been examined (with the exception of the demonstration of the software tools that each team uses in prevision of a future integration). A survey of the current situation has been established and we reached a consensus on the short and long term plans for the future.
Welcome words, program, thanks to the sponsors
(Eric Bischoff & Thomas Diehl)
Status report from the national team leaders
Relations with other Free Software projects
Writing new documentation
Technical problems (web)
Technical problems (apps)
Demonstrations (installation and usage)
|20:00||Social event at "der Pleitegeier"|
Technical problems (doc)
policies and priorities
Conclusion, farewell words
(Thomas Diehl & Eric Bischoff)
Visit to Caldera offices
Almost all the teams have finished applications translation by now. Documentation rewriting for KDE 2 is 50% complete. Now it's time to start translating the documentation itself.
If there are opportunities to coordinate dictionaries across projects (LDP, Gnome, governemental organizations, etc), we must take them.
All the team leaders should be on kde-i18n-doc ;-).
Never fix mistakes of the original texts in the translation. Instead, translate the mistake and forward a bug report.
Don't translate first drafts of documentation in the CVS: always control the summary page on http://i18n.kde.org/doc.
Do not update the <date> and the <releaseinfo> when translating - it breaks the upcoming updates process. Respect the formats 20/12/2000 and 1.01.25 to enable automation.
Share the information that on a Mandrake, first uninstall the docbook packages then reinstall the ones at ftp://ftp.kde.org/pub/kde/devel/docbook. Note: the Mandrake packager of DocBook tools knows about this and ensures this will be fixed for 7.2.
We need to publish again the docs on some web server. Find a machine first.
We should be prepared for KDE 2 press releases so they get instantaneously translated. Team leaders should subscribe to kde-pr.
Pedro Morais will write a small "howto deal with translations" for developers. Topics include anchors and calls to InvokeHelp(), context information in po files, common mistakes, who should / how to write documentation, etc.
Developpers should help more the documentation writers to write their doc, at least by answering questions.
When applications move from one package to the other, it should be posted on kde-i18n-doc mailing list.
The default style and theme has changed again lately despite the UI freeze! This means we have to redo all the screen shots :-(.
The UI freeze on messages should be respected more strictly. We know it's hard, but...
KDE does not use locales to sort. This is a localization bug.
Find a suitable technical way to add the name of the translators to the "about" box of the applications (for motivation reasons).
kwrite needs to be able to write files in UTF-8 format, otherwise the translators keep their time recoding po files.
kdevelop has a documentation mainly done for KDE 1. A big update seems necessary.
khelpcenter should show up a page to redirect people at run time if the documentation did not compile, did not exist or was not installed, to help them solve the problem.
koffice is still moving too much to be able to be localized.
kbabel should add context on the near lines in the po files.
Make sure kdelibs does not generate anchors with upper case in calls to InvokeHelp() (there seems to be a technical problem here).
DocBook is still too hard to install despite many past efforts. Continue the simplification and standardization.
Move the INSTALL file for DocBook to the web server.
Document the fact that the screenshot filename should be translated.
Document the fact that doc writers should not use revision histories, they are duplicate with the CVS logs.
Investigate if it is possible to share an user glossary between documents while keeping proper markup.
Merge the two coordination web pages (the one for writers and the one for translators) (?). Add a section "new docs already updated" to start the update process of KDE 2 docs.
The doc writers should be more visible on the mailing lists. For example, they should subscribe to kde-i18n-doc. The can also subscribe to kde-devel.
There's not enough communication between writers themselves. Create a new mailing list?
The name and email of the doc author is not enough for reporting bugs (bouncing emails) and some writers resent giving out their email, which is their right. We need a mail address for documentation bugs:
We need more style rules (capitalization, vocabulary, etc).
According to the FDL, we should copyright the docs.
In khelpcenter/contact.docbook, there should be a pointer to the teams page so people know whom to contact to help translating.
Move the visual dictionnary from http://i18n.kde.org/doc to khelpcenter.
To encourage people to translate the Web server, the news should be separated cleanly, thus enabling to translate only what is more static.
There should be a program to detect conflicts between menu
accelerators at run time in a Qt application.
Note: this program has been developped directly at the congress by Matthias Ettrich and is named "Dr Krash". It's something really great :-).
Number of persons per team vary from 1 to 20 very active people, and usually the same quantity of occasional translators, with an average of 10 active people per team. If we take a reasonable ratio for the teams that were not represented at the workshop, we can estimate that KDE has more than 300 active translators and the same number of occasional helpers. These figures do not include the doc writers (25 active and 35 occasional) and the technical teams (4 active). Occasional helpers sometimes make lose more time than they help gain because of bad quality.
Motivation is mainly ensured by having people's names in the newspapers and the files. Other reasons for helping are altruism, thankfulness to KDE, motivation by guiltiness, being paid by commercial companies to help, and bad memories of proprietary software. Articles in newspapers always bring new volunteers but a lot of them do not stay.
Some teams divide the work by package (kdebase, kdelibs, etc), others work on a per-file basis. In all teams, only a few people have CVS access. A lot of coordination work is always necessary besides the repartition of work; edict rules, maintain local web site, welcome newcomers, answer or forward questions, dispatch tools and other resources, explain a lot, and last but notleast, discuss vocabulary.
Mainling list are the preferred way to share information. The Portuguese team directly puts the work to translate/already translated on a web site, like it used to be before the move to kde-i18n. There is a strong interest on doing this aggain for all teams.
A lot of teams suffered people disappearing after KDE 1. They lost a lot of time and people due to instability of early releases of KDE 2, people resenting to install it. Same problem for DocBook, even if it was clear that some people could mark up and/or validate for the others. But now most teams finished the application messages and will start translating the documentation which has been half rewritten by now. Only a few teams translate the KDE web server, the main problem being the news. The French team translates the news and send them over to a special mailing list with about 500 subscribers interested in KDE's life. This team also collects and forwards a lot of bug reports.
On the tools hit-parade, kbabel is the star. Of course vi and emacs (with or without po and psgml modes) are mentioned a lot too. Next come midnight commander and kdedict. A lot of small home-made tools also exist and would gain by being merged into kbabel or at least being gathered on i18n.kde.org.
Most teams have already moved to UTF-8 encoding. The remaining ones are requested to do it urgently. This change is too prematurate for doc and will probably done at the same time as move to XML. Some teams have problems with fonts and locale (like two letters missing in iso-latin 1 for French and Slovak). firstname.lastname@example.org and the Czech and Slovak teams might help a lot on these issues. Distributions are requested to help fix localization problems.
Some teams already share dictionnaries with other projects (Gnome, Mozzilla, etc) or institutions. Some teams have to face the varietions on their language (Portuguese, Spanish, ...). All the teams have problems on how much technical terms have to be translated from English, the extremes probably being Italian (translate almost no technical term) and French (translate nearly all technical terms).
There are tight contacts and mutual help with LDP (Guylhelm Aznar) and Gnome (Dan Mueth), as well as many Linux distributions. These contacts allow to think about the following topics:
Mike Mc Bride sent a detailed message on the status of the editorial team (aka "English team") and Lauri read it during the workshop. People (and especially developers) are encouraged to read this great report that is attached to this document.
Eric was happy to announce the upcoming DocBook conversion service by email developped by Laurent Larzillière. With this service, doc writers (and translators) are not supposed anymore to install the DocBook tools.
Automatic redirection to the translated version of the main KDE web server is something nice and on which the user has full control to accept or not.
Translating a web server is a voluntary choice for big temas that are able to translate the news regularly.
Because of that, the small teams would prefer a small flag to local servers rather than automatic redirection. But the main page is already crowded enough so it looks like there is no easy solution to this problem.
French team needs more context according to whether a term is found in a menu or in a button due to linguistic conventions.
All slavic languages have problems with many assumptions coming from English languagei in strings with %1, %2, etc:
but the termination of the names and adjectives depend on the last digit of the number displayed at %1 placeholder."Are you sure you want to delete this file" "Are you sure you want to delete those %1 files"
The future of kbabel is:
Use ksnapshot, it creates nice lightweight screenshots.
Translators are encouraged to localize the name of screenshot files. (Note: it's the same for chapter and section IDs, but not for anchors).
It's a quite complicated licence intended for documentation (and books in general)
It splits the document into several parts:
Basically at KDE we will produce documentation with no invariant sections.
Can be localized by changing:
They should be in unicode's formal U-xxxx; notation.
The philosophy of this standard impones to think in terms of semantics, not of desired rendering. This is very important.
For user glossaries, like the current visual dictionnary after it has moved to khelpcenter:
If we want to mark them up like DocBook documents, it's not trivial to share them between documents. Some work on this might be needed.
For translation glossaries, kdedict seems the good format if we want to check consistency automatically.
In November, 1999, the KDE Editorial Team (at that time called the KDE English team), was non-existant. The previous documentation coordinator had stopped answering his emails for many months prior to my contact with anyone on the KDE project.
I signed on to document KWord, and began writting. At this time, I was the only member of the documentation/translation team who belonged to the English team. When I commited my first attempt at KWord documentation (December 1999), three people wrote me directly to ask how they could help with KOffice documentation. This was the full extent of the "English team" until March 2000, when it became clear to me that no one was stepping forward to help coordinate the English team, I contacted Eric to offer any help (initially in an unofficial position) in this area. After a few emails between Eric, Fredrik and myself, I accepted the role of heading up the English team.
In April, a general call was put out on the KDE Home page, and several other KDE related locations, asking for volunteers to write documentation. Over 60 people expressed interest in helping. Unfortunatly, at the time, KDE was very much an alpha project, and many of these people became frustrated with the technical hurdles of downloading, compiling and installing KDE at that stage, and left the project. Others have left for reasons outside of KDE (school, family, personal tragedy, etc), and today, the Editorial team consists of approximately 25 members. Nearly all of these people have commited at least one piece of documentation to the CVS, and many of them have commited 3 or more seperate applications.
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.
The KDE Editorial team is organized as follows:
Coordinators: Mike McBride (team coordination, recruitment, helps documenters with technical problems, maintaining/editing CVS for the team, misc tasks), Lauri Watts (docbook markup, documentation consistency, proofreading documentation)
Working with the two coordinators, are documenters, which make up the greatest proportion of our team
There is currently one person, who is proofreading documentation and watching for application changes.
The current status of the KDE documentation project can always be assessed at http://i18n.kde.org/teams/en/current.html.
This page lists all applications which the documentation team is aware of, and what status they are in with reguards to KDE 2.0. After the release of KDE 2.0, the format of this page will change, but this will still be the most organized way to see how things progressing.
Translators will be more interested in the "Work in Progress" page, located at http://i18n.kde.org/doc/work-in-progress.html.
Which lists the documentation files, in order of last update. It also groups each help file into a category (Done, Still using KDE 1.1.x documentation, Deleted, etc).
Approximately 50% of the documentation is completely up to date for KDE 2.0. Focus has been placed on documentation for applications that are either very popular (Kmail, konqueror, konsole, kscd, etc), are used by new users (aKtion, kfloppy, etc) or that are more complex (Kmail, KWrite, etc...). This was done because it is likely that these are the applications that users will refer to the help files the most. Approximately 6 or 7 applications have no documentation at all. These are applications that are new to KDE, and they had no previous documentation. When a user selects help, they are presented with a small help file, which informs them that documentation is not complete yet, and suggests they visit the kde web page, or use the kde-user mailing list for answers to questions. The remainder of the applications are using KDE 1.1.x documentation. These applications fall into one of three categories: Applications which were not stablized until late in the process. A good example of this, is Knotes, which has only stablized its interface and operation in the past couple weeks. Games. The previous documentation for games generally contained good information on how the game is played. They were lacking information on installation, menu entries, etc. Advanced applications. A good example of this is kwuftpd. It has been difficult to find someone on the documentation team who feels comfortable writing documentation about this program. Most of the members of the documentation team are not network managers, so sometimes there is a technical hurdle to overcome.
My initial goal, when I started working on this project, was (of course), to have all documentation updated for KDE by the release of KDE 2.0. This goal has not been achieved. Some of the problems that the team has encountered, I expected, and some problems caught me entirely by suprise. I am, however, pleased with the progress that the KDE documentation team has made in these past 6 months when I consider where we were in April.
The infrastructure is in place, and most of the bumps have been worked out regarding coordination and communication within the team. There is now a KDE editorial team website (http://i18n.kde.org/teams/en/index.html) , which contains a lot of information. Obviously there is more that I would like to include on that page, but it is a starting place for anyone who is interested in helping us. The new application licenses are working well. It is now possible for the documentation to include any of the major licenses that are in use in KDE applications.
There is a large communication gap which exists between the editorial team, and the developers. I have tried to "get the word out", that the editorial team is out, and hard at work, but I still get notes from developers who "just found out there is a documentation team".
I have sent messages to the kde-devel mailing list, but I am sure that developers (I do this myself), only read the messages that they think apply to them. So when a message appears about documentation, they skip right over it, and it never gets read by the people who need the information.
I think a better solution, is to improve the web presence of the documentation (and translation) teams. Currently, the Editorial team web page is buried so deep, I have to give people a URL for them to find it. There has been talk recently about updating and changing the KDE web page. I will work with the web designers to make it easier for people to find out how to help the KDE documentation and translation effort.
It is also necessary to improve the content of the documentation servers. After KDE 2.0 is released, I will talk with Eric, Fredrik, Lauri and anyone else interested in improving the web site. My goals would be to make a site where people could:
Browse through the applications of KDE, and get a quick summary page on the application, so that new users could find out which application suits their needs the best. Use this menu so that users could download an updated copy of the documentation, download a PDF file of the documentation, read the documentation on line. They could also send a message to the application developer, the bug system or the documentation developer, through email links. Provide useful instructions on installing new documentation or on internationalization issues. Provide a system so that application developers (whos application is not included in the base packages), can add their documentation and links to the system. Provide an easier way for people to volunteer as documentation writers or translators.
This increased presence on the web, will show the developers that the documentation efforts are important and effective.
There is a lot of information that is discussed and decided on in informal circles (private emails, irc, etc). This is fine, and is often the most convenient way to discuss information, but this information must then be recorded, if it impacts people who were not involved in the discussion. Some examples of information that was not available to documenters and translators who needed it are:
I propose that two web pages be created (and updated).
A permenant KDE release schedule. This should be a permenant fixture in the KDE web pages. There should always be some comment about when the next release is planned. Early on, the release schedule could be vague ("The release of KDE 2.01 is expected to occur in the first quarter of 2001"), but as the project gets closer to release, the web page should become much more detailed and specific. Since this is a schedule which is primarily driven by development, it should be maintained by someone who is intimately involved with developement, and who is included in discussions concerning changes in release dates.
Another page should be created that lists which applications are currently within each package, who maintains each package, and the primary maintainer of each application. A year ago, there was a page like this for the KDE 1.1.x releases, and it was very helpful to me. I am willing to maintain this page for the project if I can get cooperation (people need to let me know when things change), and the current information (who maintains what).
It is very important that these pages are updated on a regular basis.
Developers do not respond to documenters requests for information. This even extends to documentation coordinators (Lauri and myself).
This produces several effects:
The solution to problem is obvious. The question is how to convince developers that this is the best course of events. It seems to me it is in the developers best interest to answer questions from documenters. Every bit of documentation that the documenter writes, the developer doesn't need to worry about. A good manual should prevent the developer from answering the same question many times over after its release. (Even if the question is still asked, a polite RTFM will answer it now). It is not unreasonable to work with documenters the same way you work with other developers on a project you are programming on. I hope that everyone involved, will try to continue to encourage developers to work with documenters.
Consistancy. We still need to work on some consistancy issues. These will be corrected, after the KDE 2.0 release, when there is more time, and when these issues have been decided. Some issues are:
Naming programs (KControl, Kcontrol, kcontrol, etc). Do we include application web sites (they may change too often....)? Snapshots. The standards for snapshots was changed part way through the 2.0 update. Some screen shots were not redone.
There are also some markup consistency issues. These will also be reworked as time allows after KDE 2.0.