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

[Jonathan Jesse]

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?  Is it really that hard to
contribute to KDE-Docs?  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?

As far as I know there is currently not a wiki -> docbook plugin that works
constistent, once again something the Ubuntu Doc team has tried to get to
work correctly in MoinMoin -> Docbook and also Docbook -> MoinMoin.

Jonathan

On Tue, Aug 19, 2008 at 6:23 PM, Duns Ens <dunsens at web.de> wrote:

> Hi,
>
> I have already posted this to the kde-devel list and on my blog here:
> http://kde.blogsite.org/?q=node/56
> kde-devel comments concluded in something like: it is good idea to use a
> wiki
> but the wiki markup needs to be extended to get the same semantics like
> docbook has. There is also the docbookwiki project which natively supports
> docbook, but is not sure to be maintained and featured enough for this
> project. MediaWiki would need some plugins to add the necessary markup for
> docbook like semantics. Unfortunately I have other stuff to do, some
> plasmoids
> and smaller bugs in the pipe and cannot help myself.
>
>
> -----------------------------------------------------------------------------------------------------
>
> I have had an idea way back about improved documentation for KDE which I'd
> like to share since Harald has pointed out the miserable state of
> documentation in KDE. I know that ideas are only worth one cent or so
> compared
> to the implementation, but still I think it would be really helpful:
> My idea is to use an english Wiki for documenation. This might not be new,
> but
> what I mean is to actually integrate the internal help with an online Wiki.
> That way users can and would write the documenation themselves. This would
> have two advantages: a) the documentation would be most likely better than
> what it is now (this is not hard to achieve...) and b) it is a much easier
> way
> to start to contribute to KDE than specific translation or bug hunting
> stuff.
> Just link from the doc page to the online Wiki for updodate docs and there
> propose to fix it if it is outdated, wrong or missing.
>  Then pull the Wiki content before string freeze from the database, add
> screenshot media as uploaded by users and convert it to the docbook. Next
> step
> is that the maintainer reads this article *one* time and checks for
> mistakes
> or shortcomings as well as docbook fixes. And then move it to the
> translation
> team.
>
> Guessing the interest of most developers and their personal fun factor it
> is
> very unlikely that the documenation will be done sanely, completely and
> reliably ever, users would be much more reliable because they are plenty
> and
> they use app documentation (at least a view of them) and they know what
> information they missed.
> The advantage over a drop of the whole doc stuff inside KDE is that you
> have
> clear maintained versions shipping with each KDE version and there *are*
> still
> offline users around... + you don't get a versions mixup: Many distros will
> ship specific KDE versions for years and it might quite differ for lets say
> 3
> years = 6 KDE versions. Of course you could do online versioning only as
> well,
> but serious reviewed offline documentation is really more professional. I
> guess that it is a must have for the default de of the major distros, e.g.
> mandriva.
>
> Cheers,
> duns
>
> P.S.: Originally I've although thought to link to a Wiki page from each
> KMessageBox automatically, so users can share experience with certain
> errors
> or infoboxes they don't know how to deal with and will make it more
> transparent where the error could be caught better. Of course this is
> related
> to bug reports as well.
> _______________________________________________
> kde-doc-english mailing list
> kde-doc-english at kde.org
> https://mail.kde.org/mailman/listinfo/kde-doc-english
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.kde.org/pipermail/kde-doc-english/attachments/20080819/4ab06809/attachment.htm