Using userbase for manuals

[Chusslove Illich]

>> [: Aurélien Gâteau :]
>> I know at least one wiki which is git-based: [...]
>
> [: Ingo Malchow :]
> [...]
> Additionally we will loose support for quite some plugins, most notably
> the translate extension, which is integral part of this entire discussion.
> So we would be back at manually copying the english original and
> translating an entire page without being notified of further changes to
> the original.

Maybe, but not relevant. Every conceptually different documentation workflow
needs specialized translation workflow (or specialized adaptations to an
existing translation workflow). VCS-wiki combined workflow is conceptually
different from VCS or from wiki workflows alone, so it would need yet
another specialized adaptation for translation. Which is just fine, so long
as there is someone to do that job.

> All that for the sake of using a commandline tool instead of a browser?

This sentence represents a deep rift in thinking. Which is just fine. There
is no need at all for everyone to use the same documentation workflow.
Consequently, there is no need to decide about which one workflow that
should be. Instead, every project should pick its documentation workflow/
format, either one that is already integrated to some degree into KDE
technical structure (currently: in-repository Docbook, over-the-web
MediaWiki), or something else. This choice should be made by the
documentation maintainer for the given project.

In their choosing, most projects will want to take into account possibility
of translation too. If translation mechanics are not already in place,
project maintainers may add it themselves, or find someone else available to
do that. In the case of a new (non-Docbook) strictly in-repository
workflow -- documentation source strictly found in project's code repository
and strictly updated in usual VCS fashion -- I will be that "someone else"
available. I will make translation mechanics smoothly integrated into
workflow of traditional KDE translation teams (the people who now maintain
translations of 1,100,000 words of documentation). When you have written and
plan to maintain (as opposed to "ooh, I'm sure it'll be just great") some
such documentation, write to kde-i18n-doc or to me directly to arrange for
translation.

Another point, about "converting to Docbook" that is mentioned in several
contexts, both in this thread and before. There is only one and a half case
where this is sensible. One is when you are picking up maintenance of a
given piece of documentation, and your preferred format is Docbook. The
half-case is as a kludge in build chain, such that the Docbook files are
temporaries, or analogous to "installed binaries". In any other context
converting to Docbook is plain wrong, so forget about it.

-- 
Chusslove Illich (Часлав Илић)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20120704/7acd6f64/attachment.sig>