58

Documentation takes many forms. Existing resources include manuals (KDE Handbooks, UNIX man pages), Internet forums, Wikis, Tips of the day, and Clippy (sort of a horrifying after-thought). Manuals tend to offer integration with the system, forums allow users to ask questions, Wikis allow collaboration, Tips of the day can introduce users to features they wouldn't otherwise discover, and Clippy is sensitive to context and to the user's actions.

My idea is to provide an application independent interface (Plasma?) to a documentation system that looks up, presents, and allows editing of documentation. History indicates (Clippy, Tip of the day), that avoiding obtrusiveness while maintaining availability and discoverability is difficult.

I suspect Nepomuk technologies can be used to annotate documentation so its relevance to a context can be assessed. I imagine providing relevant documentation automatically on a consistent basis to be difficult. Someone smarter than me would need to tackle this. Many of Plasma's DataEngines can provide useful context - time, open applications, current application, location, and, no doubt, more.

I see Google's Wave protocol as an excellent match for providing the correct blend of interactivity and static documentation. A new wave can be started when a user has a question. A robot might parse this, and provide links to waves it suspects to be relevant. Other users can also respond to the question with any knowledge they have. Tagging could be done both manually and automatically. From the point of a Wave having a response, users could then modify the Wave into something resembling proper documentation.

Now that's a rather long post and I'm somewhat distracted, so I probably missed something important. Thanks for bearing with me thus far; I'd love to hear your thoughts and comments.

P.S. I should note that Wave is similar to e-mail, in that multiple Wave servers can exist, and users can sign up with a Wave server of their choice and expect to be able to interact with users on other servers. See http://www.waveprotocol.org/.

I really do think that, "collaborative documentation editing" would be a big plus. I've often seen out-of-date screenshots (Dragon's manual) or UIs that have changed without a change in the documentation, and it would be nice if e.g. I could edit it directly in KHelpCenter and have the changes automatically sent to the necessary people.

There's this rather cool thing called UserBase - so new, it was started only 15 months ago That's exactly the place for collaborative document editing. If we want up-to-date manuals, get them started here. It doesn't matter at all if they are not perfect - time and edits will fix that - and the developers will welcome anything that saves them time and effort. http://userbase.kde.org

Great idea could be wiki/forum. User put topic like: How change background. Users answer and each answer is separate chapter. Additionally each response should have tags/link to other pages, like control center, plasma preference dialog, etc.

System will regenerate many wiki pages automatically and mods have less work with check response is true.

Lots of user Hints and Tips like that are already on UserBase. There are even lots of screenshots and screencasts explaining things. It doesn't happen without effort. If everyone documented one item that they use regularly it would be amazing how much information would quickly become available. Join us, and make it so.

Thanks for the reminder about UserBase - it's an excellent resource for this idea. The way I see this however, is more as an /interface to/ UserBase. UserBase offers the collaborative editing, but doesn't offer integration with the environment or a convenient place for users to ask questions. I think questions are one of the best seeds for documentation - I find a ridiculous number of solutions to my problems on forums.

Besides collaboration, my idea is to include integration, and interactivity. None of these are new, but they haven't been combined. It's the combination that I see as being so powerful. "If everyone documented one item ...": that's exactly my vision too. This is about making that easier.

I should add, that as an interface, there is no reason to restrict the topic of documentation to KDE - I would expect to integrate documentation for non-KDE applications as well, and even for system related issues.

HikingPete wrote:Thanks for the reminder about UserBase - it's an excellent resource for this idea. The way I see this however, is more as an /interface to/ UserBase. UserBase offers the collaborative editing, but doesn't offer integration with the environment or a convenient place for users to ask questions. I think questions are one of the best seeds for documentation - I find a ridiculous number of solutions to my problems on forums.

That's not ridiculous at all, that's what forums are for - and Mialing Lists, of course. What *is* ridiculous is that no-one ever remembers or takes the trouble to add the solution to their problem to Userbase. Userbase should be the first place people can expect to find a solution to a KDE problem, but it will only be so if we all work at collating the information.

Besides collaboration, my idea is to include integration, and interactivity. None of these are new, but they haven't been combined. It's the combination that I see as being so powerful. "If everyone documented one item ...": that's exactly my vision too. This is about making that easier.

Discussions have started about how we can better integrate between the various resources, but time is limited for all of us, so don't expect miracles. It will happen, I'm fairly sure, but not in record time.

As for exactly what should go on userbase, remember that it is on a KDE server, and should therefore be primarily concerned with KDE applications. However, that would not necessarily exclude system-related topics. Non-KDE applications are a different case. Documentation for them is not the responsibility of KDE. Questions, though, that concern relationship between a non-KDE application and KDE itself are valid. Take for instance the information about integrating Firefox with KDE. You will find one lot of information on the forum Tutorials and another lot on http://userbase.kde.org/General_KDE_FAQ ... ntegration. Integration of the information is needed, and I haven't yet had time to do that.

There's a start for you, then - why not take on that task?

I think a good start would be having KHelpCenter get documentation from the UserBase wiki, or replace it with a new Help application that does that...

Edit: A better start would be to address the inconsistency between various application pages, see my comment here.

Madman wrote:I think a good start would be having KHelpCenter get documentation from the UserBase wiki, or replace it with a new Help application that does that...

A better start would be getting good enough information on the UserBAse wiki so that it *can* be used. Talk is cheap. Results come from effort.

I've been documenting Konqueror over the last few days, if that counts...
But I wasn't personally sure whether to change the layout to be more consistent with other apps, or which app to make Konqueror look like...

Sure it counts Your comments have already been re-arranged (not by me). The information is still there, but in a different form. That's one of the difficulties of social documentation - you do what you think best, but someone else can always change it, as you changed the original information.

I do think the benefits outweigh the problems, but it's not always comfortable when you see your work being changed.

I wouldn't mind if they just changed it, but they've reverted it back for some reason... Oh well, I've asked about it in the discussion page.

I seem to remember discussion about a wiki before, but it was decided to be a bad idea for some reason.

I still think this is a good idea.

Huh? Userbase is a wiki and has been going for 15 months now. The page Madman referred to was reverted by accident. He contact the person who had reverted it, got an apology and his work put back. Accidents happen. Wikis depend on users adding to them. Join us at http://userbase.kde.org/