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

[Albert Astals Cid]

A Diumenge, 29 d'agost de 2010, Anne Wilson va escriure:
> 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.

I do think it's better if we go one scenario at a time.

Albert

> 
> Anne