On Fri, Jul 21, 2006 at 12:08:48AM +1000, 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... > [...] > 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. 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. > 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.) Also, when users see something 'cool' in the User's Guide, they can cut & paste it directly from the LyX file, which gets them going quickly. > 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. > Cool, but can you make this work on all the very different platforms that runs LyX? A search engine on the web might be easier to pull off. And of course one should be able to use LyX on a machine that not necessarily have a web browser at all. > 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. > > 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. > The right approach for software documentation depends a lot of the intended users, the platform, and other aspects of the environment in which the software will be used. The perfect approach for one project may therefore be wrong for another. Helge Hafting
