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 (⪚ 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." > Excellent improvement, I'll use it in the docbook. Many Thanks. -- Burkhard L?ck
