I would only suggest some minor change in wording, and an added paragraph explaining the problem before addressing the solution.
One question - it would be nice if we could be consistent with use of the words documentation, manual, and handbook. They seem to be used almost interchangeably. This confused me a bit as a new KDE user, until I just got used to the terminology. I don't know if this is addressed anywhere in the KDE documentation. One other possible reason for not finding the manual is that it got installed in the wrong place. I believe this is only likely if the user compiled/installed the application himself - in which case he should know better, and should probably go to the application team and not the general KDE help, so I think it's OK to not address that problem here. On 2010.09.21 16:52, Burkhard L?ck wrote: > Hi, > > until 4.4 the KHelpcenter/konqueror displayed the error message > "There is no documentation available for %1." and additionally a > modal dialog with the error message "The file or folder help://%1 > does not exist" in case a documentation was not found for what ever > reason (not installed, no documentation, bug like wrong/missing > X-DocPath etc.) > > Dealing with bug reports on b.k.o I get the impression this behaviour > is not more user friendly than a KDebug() output in a konsole, it > does not give Joe User any hint how to get the missing documentation. > > In kde 4.5 the behaviour changed. If a documentation was not found, a > docbook named documentationnotfound will be displayed. This docbook > should explain what happened and what to do to get the requested > information. > > I have quickly written a draft for this document: > > "The requested documentation was not found on your computer. Normally, KDE looks for application manuals in a location that depends on how KDE was installed on your computer. There are a number of possible reasons why it could not find the documentation you requested. The document might not exist, or it may not have been installed along with the application. > How to solve this issue: > Search on the <ulink url="http://docs.kde.org/";>KDE Documentation > site</ulink> for the requested documentation. If you find the > documentation on that site, maybe your distribution ships a separate > package for documentation (⪚ called kdepim-doc for all > applications from the kdepim module like &kmail; &kontact; &etc;). > Please use the package manager of your distribution to install the > missing documentation. Start by searching the <ulink url="http://docs.kde.org/";>KDE Documentation site</ulink> for the requested documentation. If you find the documentation on that site, your distribution might ship a separate package for documentation (⪚ called kdepim-doc for all applications from the kdepim module, like &kmail;, &kontact;, &etc;). Please use the package manager of your distribution to find and install the missing documentation. > If you have done that, but still get this page displayed instead of > the application handbook, you probably found a bug in the &kde; help > system. please report this on the <ulink > url="http://bugs.kde.org/";>KDE Bug Tracker</ulink>. If you have done that, but still get this page displayed instead of the application handbook, you probably found a bug in the &kde; help system. In this case, please report this on the <ulink url="http://bugs.kde.org/";>KDE Bug Tracker</ulink>. > If you find no documentation on the <ulink > url="http://docs.kde.org/";>KDE Documentation site</ulink> the > application does not have an offline documentation, please report > this on the <ulink url="http://bugs.kde.org/";>KDE Bug Tracker</ulink>. If you do not find any documentation on the <ulink url="http://docs.kde.org/";>KDE Documentation site</ulink>, the application may not have offline documentation. Please report this on the <ulink url="http://bugs.kde.org/";>KDE Bug Tracker</ulink>. (I would either say "offline documentation" or "an offline manual") > > In case the application does not have an offline documentation use > the online ressources <ulink url="http://userbase.kde.org/";>Userbase > Documentation</ulink> and <ulink url="http://forum.kde.org/";>KDE > Community Forums</ulink> to get help." In case the application does not have offline documentation, you should use the online ressources <ulink url="http://userbase.kde.org/";>Userbase Documentation</ulink> and <ulink url="http://forum.kde.org/";>KDE Community Forums</ulink> to get help." > > I am too much involved in the kde documentation system, so I can't > imagine if this draft is really suited for Joe User. > > So please anybody on this list step up and comment/improved this > draft: > > Does Joe User understand what to do? > > What is missing, much/less to technical, needs more explanation? > > Better wording? > > Any more examples how distributions seperate and name the > documentation for an application or module? I use Gentoo, which is source based, and may have a separate "ebuild" to control the compilation and installation of each application - so it is possible that each one has a different "use flag" to control the compile/install of the documentation. It might be reasonable to add "If you use a source based distribution, such as Gentoo, be sure that there are not any configuration settings (USE flags in Gentoo) that might have disabled the installation of the documentation." > > Thanks. > > -- > Burkhard L?ck Jack Ostroff
