Using Wiki for KDE (User/Devel) Documentation

[Jarosław Staniek]

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.

3. How to glue these two worlds - easy content management with Wiki and
Docbook-universal intermediate XML format? The proposal is to keep "source"
format for the content as wiki data and:
a) export it to docbook when final (static) docs in HTML/PDF/PS format are needed
b) export a single or multiple pages as Wiki (raw) language so you can easily
do your editing offline and send the changes back
c) additional advantage: using wiki we can have "live" user comments, as you
can see e.g. within mysql and postgresql online documentation. These comments
are always stored in context of a given page, so can be easier turned into
documentation improvements.

4. It's not reinventing of a wheel:
- Dicussion about Docbook <-> Wiki conversion:
http://edukalibre.org/meetings/third/slides/wiki_presentation.pdf
- Text_Wiki is an implementation of the converter:
http://pear.php.net/package/Text_Wiki
http://wiki.ciaweb.net/yawiki/index.php?wiki=Text_Wiki
- KDE developers and users already use Wiki technology for writing
documentation, eg. wiki.kde.org

a) most probably we woudln't want to allow anonymous editing (except for
adding comments).

b) using DocBook->Wiki importing tools, there could be a way to move from
existing DocBook contents to wiki

c) Particular KDE apps/libs teams could make a decision whether to stay with
current DocBook files in cvs (as a source docs) or migrate to a wiki.

d) Migrating to a wiki for a project will result that the most current version
of a documentation will be available at Wiki side. For compatibility,
conversions can be executed e.g. every night, as it's the case with i18n content.

e) IMHO, for a project there will be no overhead after moving to wiki in terms
of web server administering if we can provide a help by offering a single
dedicated host like it was the case with wiki.kde.org.

f) Docs translation. Thanks to (temporary) converting docbook files to .po
files, KBabel is a piece of great translation tool for documention teams.
DocBook sources are visible in KBabel window.  All except this could remain
unchanged. It would be allowed to use Wiki tools for english (ie. original)
content, and translators will work (this time: usually offline, using KBabel)
on DocBook sources (but: generated back from wiki), as before.

BTW: Wiki engines have (sometimes) it's own multilanguage capatibilities,but
I don't think it can work as well as with KBabel.
Additional question (may be a nonsense): What about allowing to edit Wiki
sources within KBabel window, instead of DocBook XML? I am not sure aboutthis.

5. Proposed wiki engines. These two looks like most advanced (in terms ofwiki
grammar and fair efficiency):
- MediaWiki - used e.g. by famous Wikipedia
      http://wikipedia.sourceforge.net/
- DocuWiki - specialized for creating documentation
      http://wiki.splitbrain.org/wiki:dokuwiki

I most probably missed many thinks, so let's ask and discuss.

-- 
regards / pozdrawiam,
  Jaroslaw Staniek / OpenOffice Polska / Kexi Team
  Developers Wanted! Kexi 0.1 Beta 5 Released: http://www.kexi-project.org
  KDElibs/Windows: http://wiki.kde.org/tiki-index.php?page=KDElibs+for+win32







 
>> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to unsubscribe <<