Using userbase for manuals

[Anne Wilson]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I'm not subscribed to this list, so please cc me in any replies.

This thread was pointed out to me, and I'd like to comment on some of
the points raised.

Off-line documentation -

There is an extension, Collections, which allows users to select pages
from UserBase (TechBase too, if it's relevant) that are useful at that
time - usually when you are learning a new application.  They can be
renedered as html or as a pdf, and saved to HDD or pen-drive, for
carrying around.  With today's inexpensive rewritable USB gadgets this
means you can keep things up to date easily, without having to burn
disks etc..  At the same time, the Collection facility could be used
to produce disks for off-line use - but looking at the speed that
things change, that may not be a good solution.  Taking with me an
own-language set of pages for that shiny new application does sound
extremely useful to me.

The extension has been tested on our sandbox, and basically it is
working.  Initially we used a public rendering server, but our
sysadmins tell me that we can now render on our own server, which
helps a lot, both for speed and reliability.  As usual, man-power and
time restraints are the only things holding us back.

Going on to Kevin Ottens' point about docbook and docbook translators
- - I think that time will show where the strong points of wiki
documentation and docbook documentation lie - probably they will best
address different needs, but at this moment it's too early to tell.

As for the translators themselves, I'm told that they will not like
working inside a browser - something that is essential to this method.
 However, there is a MediaWiki API that can allow gettext directly -
I'm just not qualified to discuss it.  Anyone interested might be
advised to try #kde-www or ##mediawiki as a possible source of help.

The current situation is that, using a browser and the normal
Translate interface, it is possible to export to Gettext, and easy to
re-import the messages.

Boud - I'm not arguing, but is email notification essential?  Maybe it
is, but it's possible to craft an RSS/Atom feed for Recent Changes
affecting your pages.  Would that help?

Maintainability is definitely where wiki scores.  The original pages
for an application really should be written by a developer or someone
closely working with the developers, but fleshing out with user
experience can make a huge difference.  And since translators usually
use Special:LanguageStats/your-language-code they can see at a glance
which pages have changed, and to what degree.

Eike - there is a Special:RecentChangesLinked - have you explored the
possibility of that working for you?

Burkhard's comment about always needing to fix outdated or wrong
information on the English page is important, but true of pretty well
any system.  I think it is fair to say that most people are happiest
using the tools that they are familiar with.  We have several
translators on UserBase that export the English page then work in
Lokalize so that they have those additional tools.

I'd like to draw your attention, too, to Yurchor's excellent
documetation
http://userbase.kde.org/How_To_Convert_a_UserBase_Manual_to_Docbook

Basically, as Ingo has said, we need feedback.  Tell us what you need
and, together with Niklas, we will do our level best to give you it. :-)

Something I'd really like to see is applications having links to
UserBase and forum.kde.org (maybe to a specific sub-forum) in the Help
menu.  Perhaps that's what Christoph had in mind.

Anne
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk/wUJIACgkQj93fyh4cnBdtlACff3AVV/o4jN6WFc4/0jfeMuM7
7jYAn22h6ko6cSWT+3JmC5Qwq4hNX5Hk
=RvZg
-----END PGP SIGNATURE-----