Helge Hafting wrote:
On Fri, Jul 21, 2006 at 12:08:48AM +1000, John Pye wrote:
I don't think that we should expect people to use LyX as their
documentation browser.
Sure, LyX is not my choice for a browser. But documentation
for LyX itself is a special case, see below:
Operating systems all provide good standard ways
of accessing help: Installed LyX documentation should play nice with
those so that there's one less thing for new users to learn.
Well, supplying LyX docs in pdf and html is nice, of course.
Still, the main format for LyX documentation must be LyX files.
LyX is supposed to be a document processor good for just this sort
of documents, so using anything else would show a worrisome lack
of confidence in our own software. The User's Guide is a nice showcase
for what can be done with LyX, and it is a quick demonstration of
how well LyX handles long documents. (It is quite a few pages, and
for demonstration purposes, try copy-pasting the entire thing
several times . . . no crash.)
Helge Hafting
I can't imagine first writing LyX documentation in any other format
than .lyx. Most people don't read the docs first, but turn to them
when they need to find solutions. So suppose they want to know what
the User's Guide has to say about "margins". Do you think that the
LyX: Find & Replace has been designed for the purpose of finding
information for solving problems or as an editing tool? The .pdf
format doesn't normally allow editing of the content so searching
is designed for finding keywords to solve problems with a more
evolved interface. Because LyX can serve in this capacity doesn't
mean it is optimal in comparison to a tool made for this purpose.
I think a fair estimate is that the documentation is initially
read by people who have not learned that it is cost effective to
read the documentation first, and that a huge majority of users
will be reading and searching for keywords while troubleshooting.
I think the strength of LyX is that it can convert from the .lyx
format to *other* user preferred formats which might have small
features like a magnifying glass for reading the small print of
a diagram, which isn't (AFAIK) included in LyX because it has so
little application to the focus of LyX. The Windows LyX display
is only about 90-95% of the quality of LyX displayed on Linux
or Cygwin, which is another small reason to convert it to a
format that maintains quality equality for longer readings.
It can be said that a user could glean some information by
inspecting the structure of a LyX guide self-referentially
gathering some visual clues. This seems to be a strength of
using LyX for reading documentation when compared to a pdf
reader. But if you compare LyX to the Visual FAQ by Scott
Pakin, tug.ctan.org/tex-archive/info/visualFAQ/ , you will
see a tool designed for a function LyX stretches to fill.
LyX is like a pair of pliers that can be pressed into doing
the job extemes of a couple of different size wrenches like
the Visual FAQ, and Reader with its advanced search options.
> LyX is supposed to be a document processor good for just this sort
> of documents, so using anything else would show a worrisome lack
> of confidence in our own software.
I think the claim that Lyx is the best tool for creating help
guides etc. is not the same claim as that LyX is the best tool
for reading such documents it creates, and matches or surpasses
a mature pdf reader which is dedicated to displaying and searches.
The subject: please consolidate the documentation, is I think
motivated by difficulty in finding a solution to some problem.
If the Wiki were converted to one huge .lyx file, I doubt that
it would be that helpful, though you could do time consuming
searches for some keyword, if the user knew the right keyword.
Building a faster internal storage of keywords found on the
Wiki will not be so useful to the new user, but will more serve
the experienced user who knows what concept to look for.
So a detailed back of the book type index is in a more usable
format than a list of words and their locations produced by
the search engine and it is also a faster search. The new user
perusing such an index replete with "see" and "see also" opens
the door for a serendipitous juxtaposition of chance into design.
A few shorter LyX visual faqs, each covering some major topic,
with the potential of being merged later, would stifle any
complaints about inadequate documentation being too spread out.
If wishes were horses, beggars would ride (wishlist),
Stephen
