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

[Burkhard Lück]

Am Dienstag, 21. September 2010, um 23:32:35 schrieb 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.
> 
Me did not notice an inconsistency so far, but from a new KDE users PoV that 
could be really different.

An attempt for a definition of these terms from my pov:

1) Handbook -> the application help lanched via F1/Help menu
2) Manual -> man(ual) page
3) Help for System Setting modules, ioslaves and the like, technically usually 
a docbook article, what to use for them?
Documentation as general term for all types of help (1-3)

In bugreports often the term "Help" is used.

Jack, could you please give some examples for this inconsistent usage?

> 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."
> 
Excellent improvement, I'll use it in the docbook.

Many Thanks.

-- 
Burkhard Lück