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

Wed Aug 20 04:04:38 CEST 2008

On Mittwoch, 20. August 2008 03:03:00 Jonathan Jesse wrote:
> 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?
spamfilter??? quality team reviewing changes?
> Is it really that hard to
> contribute to KDE-Docs?
not for me, but for the ones who use it. it is mostly a social and a bit a 
technological barrier for technolgical interested users. Is it hard that hard 
to compile your own kernel?
> 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?
Doc freeze on major release->app maintainer review->translation team(only 
diffs)->convert to offline  (html, PDF, docbook) on major releases and ship 
it. Then link to the online version of the article from KHelpCenter.

Please read at least the article and maybe the comments and refer to it, even 
if this is a known issue to you. It is a bit offending to ask questions that 
are answered or dealed with in the article and comments otherwise...
Why not use a Wiki?

I have told how I think about it and I am not the only one who thinks that 
this would be great (as you say about a broader discussion as well). 
Especially end users, the ones who this would try to integrate into the KDE 
contributors and the docs are for, like the idea. And sorry, the current 
documentation is not comparable to professional up-to-date documentation or 
docs from Redhat, for example. They are almost always outdated in some way. 
Have had a look at the trunk gwenview docs which is still kde 3.* and 
completely outdated that way, although it is a main app.
Wikipedia articles about apps have almost always been up-to-date when I have 
visited them. 

But it is not about flaming docbook or the doc team. It is about my personal 
experience as a (part-time) kde dev, that writing docs is not in the interest 
of devs and they have not the knowledge to express things clearly for end 
users, they have it for api docs though. And they are well done for the kde 
core packages.
By moving it to a wiki it is not mainly about improving the docs in the first 
place, but moving the possibility to contribute to a new user base, which is 
experienced with wikis and not to mailing-lists personal e-mail conversations 
which might be simply rejecting when you are a noob and are not community-
like. It also allows a-non-formal way to discuss about docs and problems so 
people can get in touch first before they are pointed to bugzilla or the 
official translation/dev teams.
>
> 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.
But there is nothing stopping one to extend the Wiki markup (e.g. MediaWiki ) 
with markup to integrate docbook like information. Techbase is a good example 
how successfull a move to a Wiki can be. The tech docs before are in no way 
comparable to the huge and up-to-date information on Techbase.
>
> Jonathan
>

dunsens

> 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