[kde-doc-english] "Documentation not found" handbook in KHelpcenter

[Jack]

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 (&eg; 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 (&eg;  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