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

[Burkhard Lück]

Am Mittwoch 20 August 2008 17:55:20 schrieb Duns Ens:
> On Mittwoch, 20. August 2008 07:44:27 Burkhard L�ck wrote:
> > 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.
>
This (to close the discussion) was not intended by me.

But you forgot the translators. There are about 15 teams with more than 10 % 
doc translations, the top ten with > 60 %. 

Please read in the kde-i18n-doc mailing list archive all the discussions of 
the last few years about doc backports.

Without cooperation with the translators your system will not work in kde 
land.

> > 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.
>
See the discussions on kde-i18n-doc

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

That is the main problem with your proposal:
> I have no idea about you 
> internals [snip].
>

Sorry if my mail sounds too harsh for you, but I am tired of all the useless 
discussion about this topic.
If all peole involved in these discussions had spend their time to fix and 
update docs, we would not have this issue. 

Btw. why not get involved in the documention team, I have updated the kturtle 
docs in trunk this evening and will backport it to 4.1.2 or .3. 
Please review and improve these docs, write just plain text with your 
improvements to this list, no need to touch dockbook.

-- 
Burkhard Lück