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/. 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 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 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. 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. 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. Cheers JP Jean-Pierre Chretien wrote: >>>Date: Thu, 20 Jul 2006 03:05:50 -0700 >>>To: Jean-Pierre Chretien <[EMAIL PROTECTED]> >>>CC: lyx-users@lists.lyx.org >>>Subject: Re: please consolidate the documentation >>>From: Stephen Harris <[EMAIL PROTECTED]> >>> >>> >[...] > > >>>swish-e is supposed to be capable of indexing a Wiki. >>>Perhaps this categorizing scheme will be quite productive. >>> >>> > >PmWiki includes it own indexing scheme: the search field in each page is able >to retrieve >match in wiki pages. > >swish-e (or similar, htdig e.g.) are useful for segmented HTML publication >indexing. > > >
