John Pye wrote:
Hi all,
I'd like to say congratulations to all on the re-inauguration of the LyX
documentation team ;-) ! The scattered documentation of LyX has
frustrated me too. I have some thoughts and ideas to mention...
First, I think that the shining example of the *delivery* of software
documentation is the PHP manual, which is at http://www.php.net/manual/en/.
SH: It seems good to me and other people hold it as an example.
In its favour: anyone can annotate a page in the manual with their own
tips and clarifications. This is great and it prevents quite the same
degree of random organic growth that occurs when people feel that they
should jot things into a wiki. I would imagine it makes things easier
for editors too: the community tells you where information is missing or
unclear. Here is an example of an annotated page:
http://au.php.net/manual/en/function.array-sum.php
This is my concern about the Wiki method too. When discussing what
is good for LyX one needs to factor in the available resources.
A limited number of developers already committed to high priority
projects, no dedicated Editor, and a small documentation team.
Perhaps a limitation of the PHP manual's user-notes feature is that
whole new pages are hard for people to add. So there's still a place for
Wiki but it shouldn't be one of the primary resources, I don't think.
The PHP people have also done a great job of providing translations of
their manual, and also provide the documentation in lots of different
formats, eg CHM for reading online with Windows, and online/offline HTML
and PDF, eg see http://au.php.net/docs.php. There is a Linux
documentation format standard over at freedesktop.org that we should
comply with too.
I think these ideas serve a much larger project with much greater
resources. LyX is cross-platform itself. It is readable in DVI,
Postscript and pdf. The conversion to html is straightforward
and XML is the next LyX major goal. "htlatex foo.tex" -> foo.html
The problem with OS specific documentation is that it is only
going to benefit about ~half of the users at most, and they
already have several formats available. The left margin toc
is perhaps slightly better/readable for chm than pdf but I
don't know of a free .tex or .pdf converter to .chm. Problems
with .chm or say kde are outside the scope of LyX and only
benefit about half the users. LyX doesn't have a reource luxury.
I don't think that we should expect people to use LyX as their
documentation browser. 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. I think
that the LyX manual should serve as a model example of a well-published
document, with HTML and PDF versions, downloadable in various formats,
etc. It should be the type of end-result document that a person setting
out to write a book or a software manunal with LyX would aspire to
produce, not an exposition of the LyX GUI.
I certainly agree, showcase comes to mind. The exposition of
the Lyx GUI could be done like the Latex Visual FAQ, the LyX
Visual FAQ. One person produced this remarkable package!
There should be a good self-updating HTML version of the LyX manual.
Ideally a local search engine could be installed that would search both
the HTML manual and the Wiki side-by-side with a single installation of
lucene, xapian, swish-e, etc.
As I understand it, this will work better with XML. Updating
comes to mind also with the Wiki index project (searchindex).
We should aspire to the PDF version of the manual being a last port of
call: online searching, CHM, Yelp (under GNOME), etc should be able to
provide nicer and more efficient ways to read and search. Although,
given what LyX is, it's important to produce a good looking PDF to prove
what LyX can do.
It took me less than 3 minutes to convert those 4 LyX guides which
come with LyX-Help into pdfs and combine them into 1 searchable file.
How long to convert those 4 .lyx files and combine them into 1 .chm
with the left margin toc or then without it? How about Yelp?
We're meanwhile trying to use LyX for documenting a project I've worked
on: the ASCEND modelling environment. So we're very interested in taking
the right approach here. I'm sure a lot of other writers, especially of
software documentation, must be as well.
Cheers
JP
I would like to the LyX Wiki displayed like a book.
Wolfram does a great job of indexing, here is an
online, hyperlinked, searchable index:
http://www.wolframscience.com/nksonline/page-852d-text
General Note/Intro to the Index
http://www.wolframscience.com/nksonline/toc.html
the toc which links to the index
http://www.wolframscience.com/nksonline/index/
I am not as experienced as you are with the nitty gritty.
But I am a good judge of books and their indexes. (ices)
Wolfram's "A New Kind of Science" is over 1200 pages
long. And if you are exploring a topic like, algorithmic
information theory, it is easy to jump to it online, scan
the entry, and if you like it, then to read it in the
hardback edition (which I have).
I have seen excellent indexes in written books, Gould's
big book comes to mind. But for a combination index that
you can read/explore online, or print out instead of
going back and forth to the index in a heavy book, this
is the *best* I've ever seen. The structure of having
pages in a book supports this index.
http://www.php.net/manual/en/
That has an extensive toc and a function index but not a
full index of the manual, which seems to be OK because of
the structure of the manual and since there is a search
function. LyX Help has a User Guide and you can find the
User Guide on the LyX Wiki along with several other
separately constructed topics/pdfs. But the terms inside
the guides/pdfs are not reported with a LyX Wiki search.
I think the Wolfram index is a work of art and I would
be happy with emulating the php manual for the Wiki.
Regards,
Stephen
