Using Wiki for KDE (User/Devel) Documentation

[Jaroslaw Staniek]

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

I didnt compare to a plain text. And even if somebody only writes plain text, 
he/she is using new-line characters, and "*" to declare list items, etc. so 
this is already almost-Wiki, their natural language. What about screenshots? 
Is there a single obvious notation for plain text to insert a filename of a 
resource? Why to deal with that two times if a doc autor can write once 
[graphics:myscreenshot.png]?

Also note, again, the proposal is not for _replacing_ plain text format 
submissions by wiki format. This is also not a panacea for a boring 
documentation tasks. This is also not a force to require permament internet 
connection. The proposal is about an alternative to current, more 
sophosticated and less automated process.

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

Developers - probably not. But non-developers? I remember there were a few of 
them asking how they could write some docs or correct existing.

Final note, after intersting, about 1.5 hours of discussion on the IRC with 
Lauri Watts (thx Lauri), we've agreed the test implementation of wiki->docbook 
converter is reasonable and possible. Since the rule is not to force anybody 
to change the habits, I will try to focus on Kexi docs as a test case.

[...]
[2005-02-21 13:45] <jstaniek> I can propose a pilot implementation as:
[2005-02-21 13:45] <jstaniek> 1) moving my (trnaslated to .en) content to wiki
[2005-02-21 13:45] <jstaniek> 2) making wiki->docbook smoothly working
[2005-02-21 13:46] <jstaniek> 3) translating docbook .en to .pl in a 
traditional way
[2005-02-21 13:47] <lauri> ok, I would insert a 0) make sure the content to be 
imported into the wiki is already as near to perfect as can be (from a 
technical point of view), so that 2) has a known good target to work towards
[2005-02-21 13:48] <jstaniek> yeah sure
[2005-02-21 13:49] <jstaniek> second stage could be: making it easier to track 
corrections kde doc team made to docbook sources...
[2005-02-21 13:49] <lauri> well, we can schedule with you too (maybe only do 
runs through kexi all in one go, right before string freezes, rather than on a 
continual basis)
[2005-02-21 13:49] <lauri> whatever works
[2005-02-21 13:50] <jstaniek> (is this required that somebody from doc team 
need to correct, say, a typo in docbook, instead of using wiki? I mean one 
particular app's docs, not everything)
[2005-02-21 13:51] <lauri> sometimes, yes
[2005-02-21 13:51] <lauri> mostly no
[2005-02-21 13:52] <lauri> but the proofreaders, for instance, are mostly also 
the british english translation team, and they usually do both at once
[...]

Let me also try to refer what Jes Hall wrote:

 > This approach requires so much more work on the part of the rest of the docs
 > team and especially the translators. Find me these dozens of people who
 > would be submitting content if we had a wiki for them to do so - and give 
me > a good reason why they're not already submitting content to the wiki we
 > already have.

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