I am suggesting that the documentations for each application be contributed "wiki-style" and be maintained and updated in real time. That way, when a user pulls up a help file or an app's documentation they can be reasonable assured they are getting the most recent documentation. Also, any user could help update documentation.

The way the KDE team is doing it now is disjointed at best. khelpcenter should operate in the same way as a kpart and should simply open the wiki page for the documentation. A file for the docs could be downloaded and installed same as is currently done for offline use or network use, but most people who are looking for "help" are also looking online.

I just think the whole docbook format and "commit" structure is exclusive and counter intuitive.

If a regular user pulled up a helpfile that was inacurate or incomplete he could update it immediately. complete with screenshots. The wiki-history would keep a historical log of changes made to the page.

Is this a do-able option?

Since documentation would need to be updated for each release this could lead to irrelevant documentation for an older release.

Perhaps it would be a better idea to copy the documentation automatically into SVN ( converting into docbook ) when the documentation freeze comes into effect, thus giving the benefits of both.

It's a good point. Just wondering if the individual app's documentation needs to be updated if there has been no update to the app under the current release?

I think it's a good idea because so much of foss documentation is minimal at best. Changes in version documentation could be preceded by the version# indicating it's relevancy to a specific update.

There's no saying that people would contribute and this would work but the current system for a number of apps doesn't and maybe it's time something new was attempted.

http://userbase.kde.org/UserBase

Cheers,
_

I am one of the team leads for the KDE documentation project and wikifying our documentation has been up in discussions now for the last 4 years. With that, there are good and bad with wikifying our documentation. First off, I have no problem wikifying documentation, but it is not the best system for maintaining documentation in my personal opinion.

I do understand that people may see DocBook/XML as a way to make contributing more difficult. That is not the case at all as myself and others typically tell people to write the documentation up whatever way they find the easiest and one of the other members will go ahead and convert it to DocBook. So if they want to do a text file, ODF, wiki, whatever, we will then convert it to DocBook accordingly.

We (the KDE Documentation Project) are constantly in need of help, and any help is great help. I think if someone came up with a bulletproof plan, or as close to a bulletproof plan, then I think we should jump on it and roll with it. However, I think we should work closely with both GNOME and the Free Desktop standards, as there is/was a project (called Mallard in GNOME) that would help us standardize ALL documentation across every desktop environment. This would be good. The nice thing about DocBook is it is super simple to properly build out in HTML utilizing the KDE styles, that way there anyone with a browser can view their documentation. Another problem with wikifying the documentation only, is it doesn't provide offline systems the ability to view documentation.

I also think that forwarding such a plan to the KDE Documentation mailing list would be great as well. It is a very low traffic list, so feel free to join.

https://mail.kde.org/mailman/listinfo/kde-doc-english

Also, if you want to help with fixing KHelpCenter, please step forward Thanks everyone!

It's just that the method of 'plugging-in' in order to help is very confusing and is too rigidly controlled. Quality control is one thing, but the method of contributing is difficult beyond comprehension! Here's an example. Suppose I noticed that the help documentation for "knetwalk" (A kde game) was woefully out of date and I decided I really liked the game and wanted to help update the help documentation for it... Under the present system I'd need to:

1. Figure out where to go on the kde website in order to find out how to contribute. Email somebody to find out how to contribute.
2. Set up my computer to use specialized programs to render the text just the way the maintainers want to process it.
3. Do the documentation and then submit it to a higher level developer so that they can submit it as a commit. OR apply for permission to commit it by myself. This process takes a long time to acheive.
4. Hope and wait to see if my changes or documentation ever actually show up in docs.

I have actually left out some steps, but you get the idea.

In contrast, If the pages were wikified I would simply:

1. Edit the wiki from my desktop and apply the changes.

The wiki tabs would indicate at what interval updates were made to the page and a kdedoc maintainer could spend their time reviewing documentation and correcting it instead of controlling it.

By the way, it wouldn't require much effort to restructure kdehelpcenter to act as a kpart portal in which a user could edit right from that app, and upload right from that app.

The issue in my estimation seems to be 'control.' That is why I suggested this option. I think I will start rebuilding the kdehelpcenter on January 1st and would like to have a release worthy product by March 10th. If you'd like to help with the effort just reply and let me know. That's one of the beautiful things about KDE. You shouldn't have to wait for permission on most things. You just do the work and let people know it's available. If enough people think it's worthy it'll be included.

Anyone interested in helping me with the work?

nixternal wrote:I am one of the team leads for the KDE documentation project and wikifying our documentation has been up in discussions now for the last 4 years. With that, there are good and bad with wikifying our documentation. First off, I have no problem wikifying documentation, but it is not the best system for maintaining documentation in my personal opinion.

I do understand that people may see DocBook/XML as a way to make contributing more difficult. That is not the case at all as myself and others typically tell people to write the documentation up whatever way they find the easiest and one of the other members will go ahead and convert it to DocBook. So if they want to do a text file, ODF, wiki, whatever, we will then convert it to DocBook accordingly.

We (the KDE Documentation Project) are constantly in need of help, and any help is great help. I think if someone came up with a bulletproof plan, or as close to a bulletproof plan, then I think we should jump on it and roll with it. However, I think we should work closely with both GNOME and the Free Desktop standards, as there is/was a project (called Mallard in GNOME) that would help us standardize ALL documentation across every desktop environment. This would be good. The nice thing about DocBook is it is super simple to properly build out in HTML utilizing the KDE styles, that way there anyone with a browser can view their documentation. Another problem with wikifying the documentation only, is it doesn't provide offline systems the ability to view documentation.

I also think that forwarding such a plan to the KDE Documentation mailing list would be great as well. It is a very low traffic list, so feel free to join.

https://mail.kde.org/mailman/listinfo/kde-doc-english

Also, if you want to help with fixing KHelpCenter, please step forward Thanks everyone!

[hr]
By the way, check out the following link. The info is already being compiled and put in a web ready format. The app simply needs to reflect this structure, and allow users to edit wiki-style.

This page is buried in the "internationalization" sub-heading, and the layout format of the page itself has not been updated since 2.0 days. The content within the page has, but the page has not.

http://docs.kde.org/

mshelby wrote:I have actually left out some steps, but you get the idea.

I totally get the idea. Is there a simple way to rectify this 100% or as close to 100%?

mshelby wrote:In contrast, If the pages were wikified I would simply:

1. Edit the wiki from my desktop and apply the changes.

The wiki tabs would indicate at what interval updates were made to the page and a kdedoc maintainer could spend their time reviewing documentation and correcting it instead of controlling it.

I really don't have a problem with this to be honest, but what about someone like me who is used to just editing the docbook straight out and actually dislike editing wiki pages?

mshelby wrote:By the way, it wouldn't require much effort to restructure kdehelpcenter to act as a kpart portal in which a user could edit right from that app, and upload right from that app.

What about people who are offline? How would they edit a wiki page from within KHelpCenter? How about people with really slow dial-up?

mshelby wrote:The issue in my estimation seems to be 'control.'

I don't think the issue is just control, but control is good in a lot of cases, especially when it comes to documentation that will be displayed on people's systems. I could imagine someone going to get help for KOffice and KHelpCenter pulls up a wiki page that some goofball has decided he/she will deface, and it doesn't get caught until who knows when. Documentation should be offline more so than online, except in the cases where you can get more help than what the documentation handles, ie. funky configs and stuff like that.

Even with documentation going to the wiki and being maintained there, that doesn't fix the issue with stuff getting stale and outdated. There are millions of wiki pages out there that do not get any love at all. The problem with documentation is a) it is hard getting people to contribute to it because it is boring as all heck to do, and b) they never stick around and continue documenting.

There has to be a much better, total plan, that will help documentation. The current process isn't helping, and wikifying it will not help it either. I am one of the leads for the Ubuntu Documentation Project, and our wikis are insanely huge. People started wikifying documentation in an effort to do this same exact thing. Now we have a wiki with a ton of stale pages and outdated documentation. That's why I am not totally for wikifying everything, as I have seen it fail just as well.

I wish there was an easy way, but there isn't. And I do not think we should deviate to far from what we have, because as soon as we do, FDo comes out with a spec for it and we will have to change everything. We seriously need to work together with GNOME, Xfce, and others so we can unify as much as possible.

Nixternal, you make some very strong and valid points. I had always just assumed that documentation would still be available in offline form same as it is now, just in a different (more simple?) write-up configuration.

Maybe the wiki-style could have a hard-coded document format or stylesheet that would require documentation and screenshots to be formatted in a particular layout or design.

Might even be possible to modify the helpcenter to allow people to add/change documentation using kate or kword as a kpart. Then the change would be submitted thru the khelpcenter application and verified (approved) and released by the kde-doc maintainers. This would ensure good quality control while still allowing input from average users. What do you think?

mshelby, I like the way that sounds, but think I would really like to see some sort of mockup before deciding 100%. I would like to definitely see the entire process easier but at the same time your idea may possibly help with preventing stale and outdated documentation. Maybe even a flow chart with your ideas might help me a bit better as well, as I think you have a bazillion good ideas floating in your head, it just takes some head-to-desk moments to get them all out of you

I like the idea of people being able to easily edit a document though. This would help if people found typos and what not to easily contribute. It could send a patch or something to a mailing list....man, you have my constructive juices flowing, which I thought were dead after writing about 5,000 lines of django code this evening. Oh my head hurts

I think you could be on to something here. We might want to start really putting forth a specification that we could send to the dev lists to get some input as well. I could even put out a blog post on Planet KDE/Ubuntu/whatever other ones I am on and get community feedback as well. Heck, I just thought of another blog post I need to do since you have me thinking about documentation here.

Keep thinking and keep posting here, keep up the great work you have got rolling in here.

A flow chart and a mock-up are good ideas. It is a bit confusing in parts. I'll work on it this evening and try to post something by 01/02/09.
Thanks for the kind words. My only goal is to get regular folks contributing. Freeing up the experienced developers who are baby-sitting the documentation process will help the overall quality of KDE.

nixternal wrote:mshelby, I like the way that sounds, but think I would really like to see some sort of mockup before deciding 100%. I would like to definitely see the entire process easier but at the same time your idea may possibly help with preventing stale and outdated documentation. Maybe even a flow chart with your ideas might help me a bit better as well, as I think you have a bazillion good ideas floating in your head, it just takes some head-to-desk moments to get them all out of you

I like the idea of people being able to easily edit a document though. This would help if people found typos and what not to easily contribute. It could send a patch or something to a mailing list....man, you have my constructive juices flowing, which I thought were dead after writing about 5,000 lines of django code this evening. Oh my head hurts

I think you could be on to something here. We might want to start really putting forth a specification that we could send to the dev lists to get some input as well. I could even put out a blog post on Planet KDE/Ubuntu/whatever other ones I am on and get community feedback as well. Heck, I just thought of another blog post I need to do since you have me thinking about documentation here.

Keep thinking and keep posting here, keep up the great work you have got rolling in here.

Hello there,

Here is an easier solution: Keep the help as is but add an "on-line help" button to the help menu. That one would redirect to a wiki with all the features and that are discussed. Everyone will be able to make additions to the wiki and the authors (or other people) will be able to copy-paste documentation from the wiki to the formal documentation.

In other works, have both kind of documentation available.

This idea isn't perfect (I can see some problems where parts of the documentation are moved to the off-line files) but is easy to implement and may actually show the proper direction for the future.

v13 wrote:Hello there,

Here is an easier solution: Keep the help as is but add an "on-line help" button to the help menu. That one would redirect to a wiki with all the features and that are discussed. Everyone will be able to make additions to the wiki and the authors (or other people) will be able to copy-paste documentation from the wiki to the formal documentation.

In other works, have both kind of documentation available.

This idea isn't perfect (I can see some problems where parts of the documentation are moved to the off-line files) but is easy to implement and may actually show the proper direction for the future.

This is an excellent idea!

Although it will not be of much use unfortunately to those without Internet access, or with slow connections ( Dialup for instance ), or who have high costs ( Mobile based access ).

bcooksley wrote:Although it will not be of much use unfortunately to those without Internet access, or with slow connections ( Dialup for instance ), or who have high costs ( Mobile based access ).

Yes. That should not be its target group. Having both methods will provide all that is currently provided plus easy access to online material and will support a centralized documentation wiki and allow everyone to instantly add documentation. Then the documentation may be moved/copied to the off-line help and the cycle will start again.

Think of it as a help collaboration tool.

Plus it is very easy to implement.