KDE • Community • Announcements
DONATE (Why?)
paypal
€

Linux Congress Documentation and Localization Workshop

Linux Congress
KDE first Documentation and Localization Workshop
Erlangen, Germany
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 first meeting of KDE translation and documentation teams has been a success. We must thank:

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

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:

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

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:

  • 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

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:

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

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.


2. Agenda

Saturday 23/09/00

10:30 Welcome words, program, thanks to the sponsors (Eric Bischoff & Thomas Diehl)

 

10:40 Status report from the national team leaders
  • accomplishments
  • projects
  • way of working
  • problems encountered (Team leaders, 10 minutes each)

 

12:30 Lunch

 

14:00 Relations with other Free Software projects
  • LDP and Gnome
  • GNU/Linux & Unix distributions
  • Dewey project
  • Li18nux project
  • Conglomerate project
  • Docbook-tools project
  • SGML-tools project
  • LSB
  • discussion: how can we standardize GNU/Linux help browsers (Eric Bischoff)

 

14:30 Writing new documentation
  • current status of the work
  • reading a message from Mike
  • quality issues: how does one write a new doc?
  • discussion: how to get it faster/more efficient/better quality (Lauri Watts)

 

15:30 Technical problems (web)
  • automatic redirection (François-Xavier Duranceau)

 

15:40 Technical problems (apps)
  • context information for strings (Stephan Kulow)
  • kBabel further improvements (Mathias Kiefer)
  • right to left suport (Hans Peter Bieker)

 

16:10 Pause

 

16:20 Demonstrations (installation and usage)
  • KDE2 help browser (Matthias Hölzer-Küpfel)
  • kbabel
  • kdedict (Matthias Kiefer)
  • DocBook tools
  • remote doc validation service
  • conglomerate (Eric Bischoff)
  • emacs in PSGML mode
  • sgmldiff (Frederik Fouvry)
  • ispell
  • ortho
  • French web site (François-Xavier Duranceau)
  • db-gui (Andrej Vernekar)
  • ktranslator
  • flexicon (Thomas Diehl)

 

18:00 Hacking session
  • fix problems
  • write doc
  • translate doc and apps

 

20:00 Social event at "der Pleitegeier"

Sunday 24/09/00

09:00 Technical problems (doc)
  • screen shots (Lauri Watts)
  • FDL licence usage
  • the anchors
  • localization of the style sheets (Frederik Fouvry)
  • DocBook philosophy and its implications
  • need for a DocBook editor
  • move to XML, XSL and DocBook 4.0/4.1? (Eric Bischoff)
  • CVS branches for doc?
  • docs on Web server? (Stephan Kulow)

 

10:00 Internationalization issues
  • unicode and other encodings
  • locales
  • fonts for non-latin charsets
  • conversion & visualization tools (Hans-Peter Bieker)

 

10:20 Pause

 

10:30 Translation issues
  • motivation
  • communication with developpers
  • putting our work online?
  • dispatching the work
  • glossaries
  • visual dictionnary (Eric Bischoff)

 

11:30 policies and priorities
  • what do we most need?
  • what do we do next?
  • to freeze or not to freeze?
  • distribute separatly docs & apps?
  • attitude towards "small" languages
  • how can we organize better? (Thomas Diehl)

 

12:30 Lunch

 

14:00 Conclusion, farewell words (Thomas Diehl & Eric Bischoff)

 

14:10 Visit to Caldera offices

 

15:00 Hacking session
  • fix problems
  • write doc
  • translate doc and apps


3. Decided action items

3.1 - Translation teams

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.

3.2 - Developpers

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

3.3 - DocBook team

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.

3.4 - Editorial team

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:

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

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.

3.5 - Web server maintainers

To encourage people to translate the Web server, the news should be separated cleanly, thus enabling to translate only what is more static.

3.6 - Troll Tech company

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 :-).


4. Presentations

4.1 - Report from the translation teams

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). villa@linux.ee 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).

4.2 - Coordination with other projects

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:

  • 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
and more generally to discuss any issue regarding internationalization, translation and documentation.

4.3 - Doc writers

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.

4.4 - Web server

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.

4.5 - Context information in po files

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:

  • 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

The future of kbabel is:

  • 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

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

4.8 - FDL licence

It's a quite complicated licence intended for documentation (and books in general)

It splits the document into several parts:

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

Basically at KDE we will produce documentation with no invariant sections.

4.9 - Style sheets for documentation

Can be localized by changing:

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

They should be in unicode's formal U-xxxx; notation.

4.10 - DocBook

The philosophy of this standard impones to think in terms of semantics, not of desired rendering. This is very important.

4.11 - Glossaries

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.


5. KDE Editorial Team Status Report

5.1 Background (where we started from):

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.

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

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.

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.
The Editorial team works with translators by helping them with unfamiliar words or phrases, updating errors discovered by translators, and by monitoring the kde-i18n-doc and kde-docbook mailing lists.

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

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

5.8 To summarized the status of the documentation project:

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.

5.9 What works and what doesn't.

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.

5.9.1 Works

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.

5.9.2 Not working well (and some possible solutions)

Problem #1

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.

Problem #2

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:

  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.

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.

Problem #3

Developers do not respond to documenters requests for information. This even extends to documentation coordinators (Lauri and myself).

This produces several effects:

  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.

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.

Problem #4

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.

Global navigation links