Re: 1.4 updates

[Telsa Gwynne <hobbit aloss ukuu org uk>]

Hi.

Rushing into print before checking, but...

On Fri, Oct 06, 2000 at 10:56:32AM +0100 or thereabouts, John Sheehan Sun Microsystems Ireland wrote:

[lots of stuff I'll come back to in a different message]

> If I look at Red Hat Linux 6.2, the Authors section of the Gnome 
> Terminal User Guide omits the feedback/bug-reporting paragraphs, 
> because to include them would invalidate Red Hat's business model.

Actually, I think it's because gnome-terminal was one of the few
applications which has always had docs! When we started messing with
the idea of templates, I argued strongly for "BUGS" sections. The 
"report bugs in application to... report bugs in docs to..." also 
came in with the templates because we wanted feedback on our
docs to come to us, and the bug reports (only) to go to the developers.

Also, I am a heavy user of the bug-tracker myself, and an advocate
of "please report bugs, it's the only way to get them fixed". :) 
 
> Should Help only describe how the application works, and should it 
> omit 'packaging' issues and 'status' e.g. "This applet has no known
> bugs" ?

No!

I argued for stealing BUGS and LIMITATIONS sections from the UNIX 
man pages because they are very very useful.

Two examples:

Bugs sections are good because: 
Reading the BUGS section man page for 'man' told me how to fix any
annoying pager problem I had at the time, and that it wasn't something
I had screwed up myself. 

Limitations sections are good because:
Well, quite simply, if someone has a particular need and tries a 
program to accomplish it, they need to know they're using the right
one. My computer experience has all been on multi-user machines, so
I am familiar with the idea of a system date for the whole machine.
However, reading the bug-tracker for the clock applets whilst doing
the clock docs, I came across several "I can't change the time!"
bugs, from people who simply intuitively expected to be able to do
that. 

So that's why the "use the date command or timetool if you have it" 
line is in there (and it needs to have a better explanation and to 
mention timetool, which is the gui for it on at least some Linux 
distros, and if there's a Solaris equivalent, that should go in, too, 
I know). Limitations is a very useful category in that way.

As to where the bugs should be directed, that's a different argument,
and I tend towards Sasha's point of view here: 

> On Thu, Oct 05, 2000 at 4:00:36PM -0400, Alexander Kirillov wrote:
> > 
> > I have two comments. First, I'd like this thing - replacing
> > feedback address by some common entity - to be discussed by developers
> > - it is not to us to decide. E.g., maybe some developers want all
> > feedback be sent ot them, not to Sun or HP, even by people who bought
> > a copy of Gnome with Solaris. In particular, I'll not change the
> > feedback address in gnome-terminal docs until I get OK from Miguel. 

Nothing stops Sun changing that, I suppose, in their version. But I 
don't think that RH "removed it" because of that. I think it simply 
wasn't in there then. 

Telsa