[kde-doc-english] Proposal to use (docbook)wiki for docs

[Burkhard Lück]

Am Mittwoch 20 August 2008 04:04:38 schrieb Duns Ens:
> On Mittwoch, 20. August 2008 03:03:00 Jonathan Jesse wrote:
> > Would a wiki really help make the documetnation better?  Wouldn't there
> > be less quality control in regards to a wiki.  Who would control what
> > went on the wiki, how would the wiki deal with spam?
>
> spamfilter??? quality team reviewing changes?
>
> > Is it really that hard to
> > contribute to KDE-Docs?
>
> not for me, but for the ones who use it. it is mostly a social and a bit a
> technological barrier for technolgical interested users. Is it hard that
> hard to compile your own kernel?
>
> > We have this converstation all the time with
> > ubuntu-docs as well.
> >
> > How would documentation on the wiki translate into a help manual for
> > offline access?  Not everyone has high speed or constantly connected
> > documentation. How does the documentation on wiki translate into
> > documentation on the client in a help manual?
> >
> > If a distro links to the documentation currently (as the Kubuntu docs do)
> > how do you deal with this downstream?
>
> Doc freeze on major release->app maintainer review->translation team(only
> diffs)->convert to offline  (html, PDF, docbook) on major releases and ship
> it. Then link to the online version of the article from KHelpCenter.
>
> Please read at least the article and maybe the comments and refer to it,
> even if this is a known issue to you. It is a bit offending to ask
> questions that are answered or dealed with in the article and comments
> otherwise... Why not use a Wiki?
>
> I have told how I think about it and I am not the only one who thinks that
> this would be great (as you say about a broader discussion as well).
> Especially end users, the ones who this would try to integrate into the KDE
> contributors and the docs are for, like the idea. And sorry, the current
> documentation is not comparable to professional up-to-date documentation or
> docs from Redhat, for example. They are almost always outdated in some way.
> Have had a look at the trunk gwenview docs which is still kde 3.* and
> completely outdated that way, although it is a main app.

Gwenview is a wrong example, the docs in trunk and stable are pretty uptodate.

> Wikipedia articles about apps have almost always been up-to-date when I
> have visited them.
>
> But it is not about flaming docbook or the doc team. It is about my
> personal experience as a (part-time) kde dev, that writing docs is not in
> the interest of devs and they have not the knowledge to express things
> clearly for end users, they have it for api docs though. And they are well
> done for the kde core packages.
> By moving it to a wiki it is not mainly about improving the docs in the
> first place, but moving the possibility to contribute to a new user base,
> which is experienced with wikis and not to mailing-lists personal e-mail
> conversations which might be simply rejecting when you are a noob and are
> not community- like. It also allows a-non-formal way to discuss about docs
> and problems so people can get in touch first before they are pointed to
> bugzilla or the official translation/dev teams.
>
There was a general problem with the kde documentation in the last years, 
which can't be solved by using a wiki:

No timeframe in the release schedules for docs, string freeze for GUI and docs 
at the same time.

Update of docs only for major releases 3.x, not for minor releases 3.x.y

So if you started to update or write docs after the GUI string freeze, these 
improvements never got it into the recent major release.
The docs were added to the next major release, but at that time the 
applications had again changed in GUI and functionality -> the docs were more 
or less outdated :-(

No surprise that kde-doc-english is nowadays a low traffic list.

But I have started to change this, with permission of the translators on 
kde-i18n-doc it is possible to backport to minor releases (done for 4.0.x, 
will come for 4.1.2.
  

-- 
Burkhard Lück