Re: [Fwd: "Document font" pref [was: Re: asking for approval for bug 160454]]

[Shaun McCance <shaunm gnome org>]

On Sat, 2006-01-28 at 14:11 +1300, Matthew Paul Thomas wrote:
> On 27 Jan, 2006, at 5:37 PM, Shaun McCance wrote:
> > ...
> > My stance is that any application that shows you long blocks of text 
> > should use the document font setting, unless the text ought to be in a 
> > fixed width font.
> > ...
> 
> Pages in a help viewer usually shouldn't be long blocks of text in the 
> first place. :-)

I'm defining long blocks of text to be more than
roughly a paragraph.  Those topics that can be
covered in less than a paragraph are hardly worth
covering.

This has plagued our documentation for too long.
We fill our help pages with bullet points telling
you the obvious, but we don't really explain things
properly.

If you can explain what something does in a single
sentence, you might as well just put that sentence
in the interface, rather than making the user click
the Help button.

Terse is fine.  It helps prevent your readers from
getting bored with your text.  But if there's stuff
that needs to be said, then the documentation should
say it.

>  Help viewer windows are also usually much smaller than 
> a typical Web browser window (because you want them visible alongside 
> the thing they're providing instructions on). And help authors -- 
> unlike Web authors -- hardly ever use fonts smaller than the default 
> (if this is even possible in DocBook).

Whether you can do it in DocBook depends on what
your toolchain does.  My stuff has absolutely no
provisions for making text smaller, because our
current interface for setting fonts makes small
fonts evil.  Any application using them is likely
to cause problems.

>  All these things make it 
> appropriate for Yelp to have a smaller default font than Epiphany does.

Long ago (a couple of years), Yelp had no way to
set the font it used.  It used the same font as
every menu, button, and label on your desktop.

People often asked either for a font preference
or for zoom buttons.  And it was always because
they wanted to make the text bigger, not smaller.
I never saw anybody wanting to make the help text
smaller.

--
Shaun