[kde-doc-english] Discussion needed - the relationship between UserBase and docs.kde.org

[Anne Wilson]

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