Bug 136146

This is a very interesting idea, though I think a proof of concept would really get people excited about it.

+votes

I vote for this wholeheartedly. 
I actually have discussed this sometime ago with Sebastian Trueg from K3B. I 
am firmly convinced that the contributions for the help part will increase 
thus making Linux itself a lot easier to use. My biggest problem when I first 
started to use Linux was the lack of info in "plain English" and not 
programmer gibberish. I think that if every KDE app would have it's own wiki 
page where every user, even if not experienced in docbooc programming (like 
me for example), can contribute easily and fast.

And the KDE-docs people would only have to monitor these sites to make sure 
that they are maintained withing standards and, of course, that nobody abuses 
them.

Count my vote.

On Sunday 22 October 2006 15:33, Jonathan Dehan wrote:
[bugs.kde.org quoted mail]

Quoting

"And the KDE-docs people would only have to monitor these sites to make sure 
 that they are maintained withing standards and, of course, that nobody abuses 
 them."

I'll be the first one to agree that reading and moderating is easier than writing text. But as it stands now, and given the awkward quality that ill-guarded wiki pages tend to turn to, it won't be "only monitoring", I'm afraid.

Furthermore, we would indeed have to make sure that the wiki pages are somehow duplicated in our KDE packages, since a) we cannot guarantee that the wiki will always be available, while unless you have a really broken system, the help center is, and b) not everyone has internet access or wants to use (paid dial-up) internet.

The idea is great, but there's too much we have to be on guard for.

IMHO outdated documentation is a rather big problem straight through KDE (to verify I just looked at konqui's installed manual on my really up to date KDE 3.5.5, you find "Version 3.1 (2002-09-22)" - that's about 4 years ago! Not blaming the developers great work, I am aware of this problem ... ;)  ).

An integrated wiki-like documentation system would be... yes, GREAT! A real advantage for really EVERYONE developing, adminstrating and using KDE! Again IMHO, it would be a revolution pushing KDE's usability far beyond everything most of us have to work with to date.

Voted!

We already have a wiki:
http://wiki.kde.org/#_For_Everyone

Given the amount of content of the kde wikipedia, I doubt that wiki's promise instant succes and always op to date documentation.

Other drawbacks are the localisation of the documentation and the fact that a wikipedia is only accessible through the internet.

Thus kde systems that are not connected to the Internet won't ship with any documentation at all. Which would be a bad thing.

With each update to KDE, include a "dump" of the current Wiki status. Of course, you'd need to check everything before it goes in, but it could help those that want to help with the documentation, but don't want to figure DocBook formatting and things like that.

Voted!

I've started a related thread in 2005:
http://lists.kde.org/?l=kde-core-devel&m=110897353004659&w=4
http://lists.kde.org/?t=110897370100001&r=2&w=4

Since Mediawiki will be used for kde.org soon (at least for development docs), it's a matter of a few good ideas how to glue the wiki to the help system and optionally offer the offline version (important).

It's not unusual too see a bg in the docs or a missing paragraph and many of us just give up because fixing (a foreign docs) requires many more steps than jsut clicking [edit] link on a web page. Wiki especially solves just that.

The remaining problem is the translation system. 

Ok

The good old wiki debate again. 

Funny how throwing the word "wiki" in anything writing related makes non-writers go "yes, lets just use a wiki and our documentation will magically just appear" and real writers cringe. 

First, writing documentation is very different from fixing a bug in a doc.

Second, who will maintain the wiki, since I can not see the manpower for weeding out the crap people produce suddenly appear. Throwing more people at a problem is what makes wikipedia more closed every day.

Third, Olaf and I are working on adding the [edit] function on docs.kde.org ASAP. This will send a diff to the docs maintainers and can be reviewed before inclusion.

I think thats what people want basically. A way to extend or correct documentation without even starting up their mail client. Since thats all that is needed right now.

It is nowhere said you have to learn DocBook to write documentation. You can simply write plain text and send it to the list.

Again, Olaf and I will add the new and improved [edit] function to docs.kde.org ASAP. 

I can not see in any way how a "dump" of a wiki can be easily integrated in our system, which allows translations into over 80 languages and thus has 25 languages translating the docs. 

When all the people asking for a wiki would please calm down for a moment and then start to think how this magical wiki can be transformed into a format allowing for well formed PDFs, translation templates, HelpCenter compatible formats, HTML, PostScript, screen reader compatible formats, ... ?

DocBook is used for a reason. But it is not needed to write DocBook to contribute to KDE documentation already. If you are not able to use a text editor and a mail program, I wonder how you want to write technical documentation. 

and again, docs.kde.org will get a [Edit] function just like kde.org.

I am strongly opposed to allow unreviewed changes to documentation.

Wow, that was more of a response than I expected,

I understand the concerns put forward here, and maybe there's a good compromise:

First, the help pages are brief and concise, so they should be the first place users go.  It would make sense to have, at the bottom of each page in the help system a "For more information from the KDE wiki, click here" and the specific wiki page would load.  This would keep in status-quo the reliable help pages, but give users more content when the help page didn't answer all of the users questions.  It would also alow developers to keep the help pages short and concise, as the user always has the option to read more on the wiki.

To respond to those who say the current kde wiki is lacking content: have you seen it?  the change to mediawiki should make contributing a lot less daunting. In it's current form,it is hardly usable.

The second compromose might be to simply make contributing to the KDE help as simple as a wiki.  Say, for instance,  You have a "Edit" button, which allows the user to make changes to the page.  When the user clicked "Done," a patch file would be sent to the documentation team.  Those involved could apply the "patches" as they see fit.

Obviously, this would involve more thought, but such a system, if implemented well, could allow anyone to easily contribute without much work, and would give the documentation people more content to work with.

While I'm not a software developer, I'm just the type of person who would contribute if it was as easy as a wiki.  I don't see why you should have to understand cvs and how the "KDE help center" works to contribute some documentation.  I suppose I could e-mail the KDE docs team, but I spend enough time playing email-tag.  

Some would say that the linux kernel develeped so well because it had many, many people looking at the code and making fixes and changes here and there.  Making a more open documentation system could result in a similar result.

Also, I just reread  Rainer Endres' comment, it appears they are already working on implimenting an edit function.

I dont know how I missed that.

You do not need to understand anything about how the khelpcenter works to write documentation. I could not tell you the first thing about it and I have contributed thousands of words over the last couple of years.

Write a page on a wiki and email someone the link, write a plain text document and email it to someone, write any format you like and email it, you do not *need* to use CVS or SVN or anything else to contribute. I will not support a system where contributers who have not gone through the process to have SVN accounts can commit documentation without it going through a documentation member. If writing plain text in an email is more than you can be bothered doing then I do not want your contributions - and I know much of the documentation team agrees with me.

The reason this wish has engendered so much heated response is because the wiki suggestion comes up about once a year. Never by a core member of the documentation team, and it's always argued against. This is the 4th time I've argued against it and these days it's gotten tiresome - it's a well known joke at conferences that if you want to rile up a documentation person all you have to do is say 'wiki' near them and they see red and start spluttering =)

I do like the idea of using the current KDE wiki as a 'scratchpad' for documentation. Again though, I will not support any system that would make life so much harder for the documentation team. We need to be able to generate so many different formats in so many different languages, that the only system I could see working better than docbook is latex - and I don't think anyone wants me to suggest we switch to that.

Le dimanche 29 octobre 2006 02:04, Rainer Endres a 

KDE has a wiki, but it's an outdated mess.