This email grew out of a discussion with Burkhard L?ck and Yuri Chornovan, using UserBase Talk pages.
It is our firm intention that UserBase should work alongside the exisitng docs systems. However, it seems that it would be beneficial to set out some premises for discussion, in order to create guidelines. I will undertake to write up those guidelines at the end of our discussion (or at stages along the way) and point people to them. As a starter, here are my thoughts about the various scenarios relating to manuals on UserBase. Scenario 1 - a brand new manual is created on UserBase. When the author sees it as complete it is checked by one of the UserBase admins for markup, then marked as ready for translation. That would normally be picked up by the docs team, via gettext (which operates from the Translate extension), for off-line translation. In order to avoid duplicating work and getting translate conflicts, we need to agree some way of marking that a manual has moved within the system. I'd welcome some thoughts on that. Once the gettext has been pulled, authors may continue to develop the UserBase version, to add new features. The author would be expected to agree with the docs team when a new docbook version should be made. Until then, any changes would not be 'marked for translation'. This allows string-freezes to be adhered to yet future development to continue without passing for translation. It is important that once we have agreed the mechanisms that we publicise the way it will work. Scenario 2 - no official manual currently exists, and the author does not yet feel ready to create one. In this case pages may be created on UserBase to be translated by anyone with good enough language skills, mainly using the on- line page translation tool. The future of those pages is a subject for discussion. We have been requested to look for ways of producing off-line documentation from those pages, particularly for users in areas where Internet access is sporadic and unreliable. We are investigating production of PDFs for this purpose - although there are wrinkles to iron out, we know it can be done. Scenario 3 - a manual exists, is up to date, and synchronised regularly - the KGpg manual is a good example of this. However, the mailing lists and forums indicate that there is a good deal of misunderstanding of the subject. It may be because some distros do not install documentation by default, but many users, particularly new ones, may not find it themselves. For some of these subjects there is a strong case for having a copy attached to UserBase. It's probably not as vital to keep it 100% sync'd with svn, but it probably should be reviewed with each major release. If we agree on that, we need to engage the authors to ping userbase admins if any additional updates are needed. There most definitely should not be updates to manuals occurring on two separate systems, as that would be totally unmanageable. Again, the key is to decide what works best, then document it. Scenario 4 - a manual exists, but it is quite old. The author, however, feels that only part of it is outdated, and would like an easy way of editing until he is sure that he has a fully updated manual to be passed for translation. Currently we have no installed mechanism for importing the existing docbook. The translate extension relies on tokens being passed between the UserBase version and the translation tool, whether on- or off-line. I have already been approached by one developer who would like to use this method of getting his manual up to date, and it could well be very useful to others. In view of this, Matthias Me?mer (pipesmoker) is working on the import problem. To date he has a full text import, and is now working on adding the images. Questions arise from this, for example, which tags should have a UserBase equivalent. Many are irrelevant to UserBase though would do no harm, other than the fact that requiring people to add very many is likely to make them feel that wiki editing is as bad as docbook editing. To date, we have <keycap> and <menuchoice> tags. Any others that make exporting to docbook easier can be defined. We want to work efficiently with the i10n and i18n teams, and are willing to consider anything that can help achieve that. We have active support from the developers of the extension, and Ingo Malchow is willing and able to implement changes at the mediawiki code level to help us get there. If it helps we could split this discussion to just one scenario at a time, but we do need your views and ideas. Anne -- KDE Community Working Group New to KDE Software? - get help from http://userbase.kde.org -------------- next part -------------- A non-text attachment was scrubbed... Name: not available Type: application/pgp-signature Size: 198 bytes Desc: This is a digitally signed message part. Url : http://mail.kde.org/pipermail/kde-doc-english/attachments/20100829/934da47b/attachment.sig
