Using userbase for manuals

[Chusslove Illich]

(Many things have been already pointed out, but I'll repeat, to hopefully
frame it a bit more concretely.)

The way I see it, there are really three conceptually independent aspects
here:

1) Documentation should be up to date, promtly reacting to changes in
program features and behavior.

2) Documentation should be translatable in a way that maximizes the amount
and quality of translation.

3) Documentation should be readily available to users.

For (3), of course it would be nice if the users should have documentation
in conditions of low connectivity, but also in formats other than a web
page. Someone should "simply" make this technically possible per the way (1)
is done, with the scope as wide as desired. One bonus is integration into
desktop environment's help viewer, such as KHelpCenter. (However, consider
that maybe not all ways of (1) are good enough for "true online"
documentation, i.e. what people called "on-line" before the web: when you
are working in a program and want to invoke help for a particular section of
it in which you are currently.)

For (2), by now it has been amply demonstrated in practice that the
translation should take place over PO files, which are automatically put
into and taken from the KDE translation repository. While noone ever
seriously suggested that another workflow can bring higher quality of
translation, some people did hope that other workflows could at least bring
higher amount of translation. But the reality is that a dedicated translator
using dedicated translation tools is an order of magnitude more productive
than a drive-by wiki contributor, and that hoped for swaths of drive-by wiki
contributors never materialized. So, regardless of how (1) is done, as long
as there is an automatic turn-around of PO files in KDE translation
repository, (2) is covered. Someone should "simply" make this technically
possible per the way (1) is done. (If documentation is written in a really
fluid manner, one should also think about freezes, if possible.)

Now (1), that is the most interesting bit from my viewpoint. The nice thing
about (1) is that I see no reason why everyone should do it in the same way,
as long as means for (2) and (3) are (in process of being) established for
given (1). I personally think that to have serious reference documentation,
a dedicated documentation author is necessary, and that wikis, for example,
can only impede that person's work; wikis *may* be suitable for "tips and
tricks" or "how to do X" loosely connected texts, but reference
documentation is another thing entirely. Maybe some programs do not need
reference documentation at all? That's fine by me, and I'd drop the current
policy that all KDE SC programs should have it.

But, when program authors do decide that they want to have reference
documentation, I don't see how any workflow can be technically more suitable
(easier to write, easier to maintain) than the documentation source files
residing right with the code, in the program's repository. To separate
documentation from the code repository, in my view, automatically states "we
don't need/won't write reference documentation". What I'm not claiming is
that documentation sources must be Docbook, and I suspect that Docbook is
what's driving many people away from maintaining documentation in this way.
I would encourage people to look into other documentation formats, providing
that they always consider (2) (do we have a format-X to PO and back
converter? how will we hook it into KDE translation repository automation?).

> [: Eike Hein :]
> [...] but the reality seems to be that we just can't get our act together
> on the offline documentation while maintaining the wiki comes a lot easier
> to us. [...]

_From my viewpoint, that which is on Konversation wiki is not reference
documentation, which you too implied in the preceding text; and not having
reference is completely fine by me, as I mentioned above. Even so, how comes
this existing content on the wiki is easier to maintain than that same
content would be in offline, i.e. within-repository form? For example, if
you modify some feature, how does wiki make it easier to detect that
documentation change is needed and to perform that change, than it would be
the case with within-repository documentation? Could it be that you are
simply driven away by the Docbook's towering hulk? :)

Maybe people who actually do want to write and maintain documentation for
their programs, but not linear-flow reference documentation, should look at
Mallard[1] (and look at achieving (3) and (2) for it in context of KDE, the
PO convertor being already available). It is again XML, but with very small
set of basic tags (easily fits into one person's head), and it was created
explicitly for writing topic-oriented documentation.

[1] http://projectmallard.org/about/index.html

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