Using Wiki for KDE (User/Devel) Documentation

[Matt Rogers]

On Monday 21 February 2005 02:11 am, Jarosław Staniek wrote:
> Last week, on #kexi we (me, Cédric Pasteur, Martin Ellis) had a small
> discussion regarding a method of developing apps user documentation in a
> way so also non-technical people, (usually not DocBook-fans), could easier
> accept. I will refer to them as "Doc writers".
>
> Our ideas and notes:
>
> 1. From http://tikiwiki.org/tiki-index.php?page=DocBookDev
> "DocBook? is intermediate XML format, very convenient for converting
> information into presentation shape. It's raw XML structure (though well
> documented) and popularity allows various templates to be applied easily to
> the same text."
> -- true, and it's not attack against DocBook
>
> 2. The proposal is to allow people to add content using wiki grammar. "Doc
> writers" write and read in text, not in a XML tree. Using XML editors is
> too often not an option. Providing DocBook styles for eg. OO.org Writer or
> LyX is not so easy as using online wiki engines, because there's related
> problem: do we want to force "Doc writers" to use CVS and play with files
> on their local disks? It could be an option to work offline, but not a
> requirement.
>

This involves people learning wiki markup, which is not necessary as the kde 
docs people will already take plain text in email and add the docbook markup. 
So wiki actually makes the barrier to entry higher!

> [snip the rest]

You seem to have overlooked the number one reason why many apps don't have 
documentation or have out of date documentation:

It is not sexy to write documentation.

For the majority of people/developers/whomever, it's tedious, boring, not all 
that fun, slow, and hard to do, even without the docbook. It requires 
planning and research, and well, i don't see a lot of developers taking time 
out of their hacking sessions to do that.

Matt
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20050221/192edea7/attachment.sig>