Re: Why is it _still_ so freaking hard to get info with images?

[David Kastrup]

Han-Wen Nienhuys <address@hidden> writes:

> On Fri, Mar 13, 2009 at 8:50 AM, David Kastrup <address@hidden> wrote:
>
>> It is a bit disappointing since the info documentation with images is
>> essential for really getting moving smoothly with Lilypond, and the
>> procedure for producing them is so broken or obfuscate that none, I
>> repeat none of _any_ lilypond precompilated versions that I know of
>> carries them, and there is no way even a clever user could be
>> expected to arrive at usable docs.
>
> At the risk of putting more gasoline on the fire: I have never found
> the info docs anything of a priority, not when Jan started it (back in
> 2003 or whenever it was) and it was always Jan who had to fix build
> errors in the process.  Given that nobody (besides you) else ever
> complained about the info pages leads me to believe that in reality
> very few people care about info pages with images.

Very few people _know_ about them.  I don't think that there are more
than a dozen Emacs developers that actually know that Info supports
images.  The intersection with Lilypond users will be minuscule, and
that is partly a chicken-and-egg problem: if you can't guess that Emacs
info can show images _and_ you can't guess that Lilypond can produce
images with info, why would you ask or complain?

That's why Lilypond's makefile info targets should make it really hard
to get info pages without images.  Because people will totally be
surprised by the presence of images.  They don't expect them.
Consequently, they won't go looking for them.  If they are on the plate,
the demand will voice itself.

> There are other data that support this too:
>
> in March, we had 1689 windows downloads, 122 mac, and 107 linux ones
> on lilypond.org.  The latter number may be skewed because some people
> will get lilypond through their distributor, but still.  I believe
> that the average windows user does not know what info is, and much
> less has a viewer for it.

Sure.  The point is that HTML is a pain to navigate.  It does not have
structural movement.  It does not have indexes.  Browsers are slow.  It
does not have document-encompassing search.

And that is the reason info has not been retired within Emacs.  At some
distant point of time in the future, the format might get changed to
HTML (with structural tags), and with a special reader that gets along
with a special HTML subset.

> Speaking from personal experience, I tend to access documentation for
> whatever I do by searching Google.  I suspect this holds for many more
> people.

I have to bash that out of people's head for some of my project: if a
project has a visible history of 15 years, people tend to find pages
with 10-year old documentation of a version that worked and installed
completely differently.

Yes, I do receive occasional bug reports based on Google searches of
outdated ill-advised pages from a computer account abandoned 10 years
ago, when the software comes with very diligently and completely,
painstakingly polished instructions.

It makes life easier for developers if they can get the users hooked on
the actual current documentation instead of search engine wisdom.

>> It is my opinion that Lilypond developers are shooting themselves
>> quite unnecessarily in the foot by the large discrepancy between the
>> high quality of the documentation and the probability of actually
>> getting to see it after a finite amount of effort.
>
> I think the lilypond doc developers are focusing on getting excellent
> HTML documentation, and I think that is a smart use of resources.

I was not suggesting replacing the HTML.  I am not too sure about the
HTML targets being produced and organized in the most obvious manner,
but in contrast to the imaged info, people _expect_ this sort of doc.

-- 
David Kastrup