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

[Duns Ens]

On Mittwoch, 20. August 2008 07:44:27 Burkhard L�ck wrote:
> 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.
I have a kde 3.5 german version here, maybe this is an issue with my 
environments, have to track it back.
>
> > 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:

Strong argument at first. Could you please conclude in the end why it is not 
possible? Don't get me wrong I don't want to offend anybody and I don't need 
the docs in person but rather for my family or people I try to help 
opensourcewise I'd like to point to a clear documentation. If the timeframe 
issue is all you are worried about this could be dealed with maybe, so your 
conclusion is disputatious. If you put it at first it looks like you are 
closed to discussion to me.

>
> 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.

Who says that one cannot backport important stuff from the wiki for minor 
releases just because I have not explicitly mentioned it in my response (but 
in the comments on my blog I guess)? Backport like it is done codewise? 
It is better to have something to backport than to have nothing to backport at 
first.
Normallly minor releases should not be necessary as they don't introduce 
features and especially no gui stuff. So I don't get your point here really.

> 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.

That was the main point of a wiki. Open parts like docs to everybody since it 
allows a new community to build around them and an easy point to start to 
contribute if you feel something is mssing. If you have googled your way to a 
power user already and know how to join the kde team and deal with mailing 
lists and stuff you are no more interested in writing docs imo.
Nobody says that the current doc team should be dropped. They could do qa on 
the wiki changes and have a look at important backports instead of create 
content themselves.
kde-devel at kde.org and #kommunity liked the idea and pointed me here. People 
have commented that they would have liked to contribute some doc stuff but 
couldn't back then. kde-devel at kde.org had a quite large positive discussion 
about it with technial issues pointed out, but none of them was unsolvable but 
rather necessary to deal with. Especially the markup extensions.

>
> 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.

This is great and could be resumed with the wiki. You can even release a wiki 
snapshot polished with each minor release since the translation would be only 
a small diff like part which everybody can view in the wiki.

I hope you don't get me wrong. I am very happy that there are people working 
on the docs as I think that they are *very* important and that is why I 
argument strongly for the wiki stuff. I have no idea about you internals and 
you don't owe me something.

Cheers,
dunsens