Re: Missing documentation
Let me make sure I understand. Also some additional comments below.
On Wed, May 05, 2004 at 04:01:41PM +0200, Alejandro Exojo wrote:
> El Miércoles, 5 de Mayo de 2004 07:06, Ross Boylan escribió:
> > In the last few days I've tried to read the documentation for a couple
> > of KDE applications (via their help menu) and the KDE Help Center
> > comes up and says it can't find the docs.
>
> This is simply because the docs doesn't exist in your installation.
This could be because I have goofed, the debian packagers have failed
to package the docs, or KDE supplies no docs.
>
> > I also recall reading that the KDE packagers could use help with the
> > documentation.
>
> The Debian policy demands that every binary (every kde application, for
> example) should have a manpage. If a package doesn't provide one, it is
> considered a bug, but packages use to have bugs :-), so help in solving that
> bugs, is welcomed.
So the Debian KDE team is specifically interested in getting man
pages?
>
> > So, is this anything I should file a bug about, or is it just par for
> > the course?
>
> The documentation in the khelpcenter, is optional in a kde debian package, so
> if you file a bug report in bugs.debian.org, I suppose that developers will
> just forward that wishlist to upstream mantainers. There are many
> applications that need help in updating, translating, and writing such
> documentation, but this is not Debian packager's fault.
Agreed. Though as an end user all I know is I don't see the docs; I
don't know why.
>
> If you want to contribute, you don't need any special skill. Read that short
> post from Lauri Watts:
>
> http://lists.kde.org/?l=kde-docbook&m=108353830010815&w=2
>
Interestingly, that page has a link to open bugs about documentation,
which are relatively few. I suppose the number of apps/applets
without documentation is relatively large. I suppose one could
respond to this either by concluding that filing a documentation bug
is silly, since everyone knows there's a lot of work to do, or that
filing a bug is a good way to focus attention on apps of interest.
It looks as if http://docs.kde.org/ shows all the documentation that
exists. kdeprintfax is not on it, so it looks as if it's missing
upstream. There is kdeprint documentation, but it does not include
kdeprintfax information. Also, here is its entire description of
kdeprint's print to fax facility: "To be written"! I think this is
something different from kdeprintfax, which allows you to assemble a
fax out of various files you already have.
Too bad that to document a program you have to already know how it
works. I suppose some of the developers might be willing to talk if
they know you were doing documentation, and there always is the source
:) Really delivering documentation is part of delivering an
application, but I know a lot of programmers regard it as a nuisance.
kdeprintfax is fairly small, so I suppose it might be doable. In
particular, it has a bunch of substitution symbols and it's probably
not too hard to track down what they mean.
> There is always an open job in KDE website about this issue:
>
> http://kde.org/jobs/open.php
>
> > I can't recall the first app, but the second was kdeprintfax, part of
> > the kdeprint package (4:3.2.2-1) from kdebase source. I didn't see a
> > documentation package listed in the suggests or recommends, except
> > khelpcenter, which is installed.
>
Your reference to man pages inspired me to check if there was one for
kdeprintfax; unsurprisingly, there isn't.
> The documentation normally is installed in the same package of the
> application.
OK, so it's probably not an "I didn't install the doc package" type
error.
>
> Best regards.
>
Thanks for the pointers.
Reply to: