Re: The documentation web

[Shaun McCance <shaunm gnome org>]

On Thu, 2007-03-01 at 16:12 -0500, Eric S. Raymond wrote:
> Shaun McCance <shaunm gnome org>:
> > > It bothers me that serious users have to learn finger habits for as
> > > many as five different help browsers: a web browser, man(1), info(1),
> > > the Emacs text editor, a dedicated GUI help browser such as GNOME Yelp
> > > or the KDE Help Center, and the venerable more(1).
> > 
> > In terms of finger habits, man == less, info == emacs, and
> > Yelp == Epiphany (alternately, KDE Help Center == Konqueror).
> 
> I think you're oversimplifying.  I'm counting the invocation
> keystrokes as part of the finger-habit overhead, too.  Haven't you
> ever typed 'man foo 2' when you meant 'man 2 foo'?

Actually, no, I haven't.  I view my man pages in Yelp.
And since Yelp shows me all the documentation I need,
I only need one set of finger habits.

> > > Additionally, I think it's perverse that Linux users have better
> > > ability to search the external Web via Google than they do to search
> > > the documentation on their own systems.
> > 
> > This is, again, a writer problem.  We can pat ourselves
> > on the back all day for having built clever documentation
> > tools, but if writers don't write the content, we're not
> > worth a damn thing.  Writers are king.
> 
> No, this is *not* a writer problem.  It can be solved very easily with
> an engine like ht://dig, provided (a) everything is in HTML, (b) 
> ht://dig is told where the HTML trees are, and (c) ht//dig's indexes
> get (at least partially) recomputed whenever a package is installed.

And (d) the documentation actually exists.  I want to write
an email to a friend about P�z Prado, the greatest mambo
musician of all time.  Unfortunately, I can't figure out
how to type an "�on my US keyboard.  How do I do it?

Don't tell me how.  Tell me how to find that information
in the documentation.  Now tell me how ht://dig would
make that process better.

If you really want a better help system, find us more
writers.

> This is one of several reasons everything needs to be in HTML.  I want
> to use the single-presentation-format property to decouple the various
> pieces of the documentation infrastructure from each other.  Neither
> ht://dig nor your browser would have to 'know' that any given piece
> of HTML is part of local documentation managed by the help system, 
> and that's how it should be.

Great.  Except that we already have text indexers that
can handle multiple formats.  Why introduce yet another
text indexer onto the system?

> > Let's look at this:
> > 
> > * We're not about to make Epiphany able to transform
> >   DocBook, Mallard, man, and info into HTML on the fly.
> 
> Agreed.  That would be too slow,

With the exception of very large DocBook documents, it's
not too slow.  And Mallard is designed so that the size
of the entire document won't impact the speed of loading
a single page.

We've been doing transformations on the fly for years,
and they've gotten better and better with each release.
My point wasn't that we won't do them; my point was that
we won't do them in Epiphany. 

> > * Thus, we have to install the presentation format.
> 
> Agreed.  That's my plan.
> 
> > * Installing the presentation format is 87% of what's
> >   wrong with info.
> > * Installing the presentation format seriously hinders
> >   our ability to adjust the formatting for accessibility
> >   and localization needs.
> 
> I don't think so.  Multi-user machines with different users using different
> localizations are not a case we need to worry about.  So we localize the
> HTML *once*, at document-lifting time, and we're done.

Why don't we need to worry about that case?  I agree
that it's a sufficiently small demographic that it
shouldn't be our primary target.  But that doesn't
mean our tools should fail them.

> As for accessibility, we leave that to the browser, which is where
> accessibility efforts belong anyway (close to the user and easily
> tunable by the user).  This is another place where we'd get to
> decouple the pieces of the documentation system from each other and
> avoid big lumps of specialized code.

Look at things like colored backgrounds/borders, text
screening, and icons and watermarks.  Rich visual styles
aren't just eye candy; they can make reading far more
pleasant and engaging.  We could accomplish much of this
with display-time-generated custom CSS (provided we can
rely on a stable structure and class usage in the HTML),
but there's a whole lot more you can do when you know
the accessibility needs of your reader at transformation
time.

> > Taking the least-common-denominator route doesn't sound
> > like pushing things forward to me.  It sounds more like
> > giving up.
> 
> Nothing least-common-denominator about HTML, not that I can see.  It's
> as rich or richer than any of the other presentation formats in normal
> use (e.g. plain text, info, and formatted man pages).

Any of the presentation formats, sure.  The appearance
of info pages in Yelp generally sucks.  That's because
the presentation format that gets installed is devoid
of any useful information.  Now, if the texi source
files were installed instead, and viewers transformed
them on the fly, we'd have some hot info rendering.

  "Choose portability over efficiency."
    -- Mike Gancarz

> > I'd call man pages a very small part of the problem.
> 
> Then you'd be wrong.  They swamp everything else in sheer page volume.
> Like it or not, about 90% of the documentation on a typical Linux
> system is man pages (and yes, I've checked this on a modern Linux).

Sheer page volume != frequency of use.  There are more
books on the tax code than there are books by Stephen
King.  Guess which gets read more by normal folks.

> > Honestly, the sort of content that's generally found
> > in man pages is not stuff most people care about.
> 
> I think that's a very patronizing judgment.  Let's write infrastructure
> that gives our users room to grow and explore, eh?

It's not patronizing.  The material in man pages is
generally only of interest to people who want to dig
into their system.  If our users want to explore their
systems, I'm happy for them.  And Yelp can help them.

But the simple fact is that the majority of users do
not want to get their hands dirty.  They just want
their computers to work.  These people constitute
Yelp's primary audience.