Re: help wanted! get involved! make Debian-women work!
On Mon, Jul 12, 2004 at 04:56:05PM +0100 or thereabouts, Helen Faulkner wrote:
> Can I ask a dumb question about manpages:
Not dumb.
>
> >Just to let anyone who's interested in this issue know, there's a missing
> >manpages project located here: http://qa.debian.org/man-pages.html which
>
> Just looked at the list. How come there are missing manpages for a
> bunch of kde things that presumably have instructions in the kde user
> manuals that you get to through the help menu. An example is kedit. I
> would have thought there was some tool that translated those
> instructions into manpages. Aren't there a bunch of tools that do that
> kind of thing?
I don't actually use KDE, but I do use Gnome and have contributed
a lot of documentation to Gnome over the years. I can explain the
issues for Gnome. I suspect they're similar for KDE.
In fact, here is a URL from the KDE documentation-writing pages
which explicitly contrasts the terse and dry style of manual pages
with what they hope to create for KDE (and which advocates
screenshots -- see below).
http://i18n.kde.org/doc/styleguide/writing-well.html
* Gnome help uses lots and lots of screenshots. You can't put those
in a man page.
* Gnome help tends to assume it's being read by a user who does
not necessarily know much about UNIX or Linux. Man pages.. vary.
* Gnome help tends to assume that the application has been
started by clicking on a launcher. There are often dozens of
command-line switches you can use when starting stuff up from
the command line. In the Gnome help, many of them are not even
mentioned. (This is not a policy I agree with.) In a man page,
each needs to be documented. Probably right at the start.
* There is a set template for writing Gnome help: write about
this first, then about this, then about this. There are
traditional guidelines for man pages, and I see Debian has
an example one too. Wouldn't you know, they're not the same.
So you'd need a fairly involved conversion program to reorder
sections. (You'd also need someone to go through and remove
every reference to screenshots, since the screenshots wouldn't
be there.)
I actually don't like the current guidelines for Gnome documentation
very much, which is why I haven't contributed a lot recently. I'd
far rather write man pages. I have so far written one. I intend
to write more. And doing it for the missing Debian man page project
seems the sensible way to go about it.
In fact, here is a URL from the KDE documentation-writing pages
which explicitly contrasts the terse and dry style of manual
pages with what they hope to create for KDE and which advocates
screenshots.
http://i18n.kde.org/doc/styleguide/writing-well.html
I hope this isn't too out of place. I am much more used to Fedora
and Red Hat than Debian, and actually joined this list to try to
get more involved in Debian and to listen and learn rather than
to talk. Sorry about that. I'll go back to lurking again now :)
Telsa
Reply to: