Hello LyXers,
I want to restart to work on the documentation but at first want to have
you OK about the HOW.
The documentation is currently out of date, many menu names have changed
since the last release, new features like change tracking are not or not
properly explained.
Then main problem I see is that we don't have somebody who's actively
working on the documentation. But besides this the inconsistent
documentation we currently have is a result that the developer of a new
feature add a section to the userguide without cross-checking if the
section is consistent with others. That can be excused due to lack of
time but for the future I propose this way:
---
When a new feature is implemented to be released in the next LyX version
the developer(s) who wrote the feature create a separate LyX-document
describing the feature. Then somebody who wasn't involved in the
development of the feature checks if he's able to use the feature as
described. This would help us to implement features user friendly
because the revisers of the document will lead to feedback about the
implementation, the usability and the stability of the feature before
the feature is released. If the feature is stable its describing
document is implemented into the userguide.
---
This sounds a bit theoretic but the current way we implement features is
not user friendly: I noticed that only a few people know the new change
tracking feature of LyX 1.4.x and those who found the menu entry for
this asked me how to use it because the feature isn't properly explained
in the docs or in the wiki. Even if they know to handle change tracking
because they've used this in MS Word, they of course ask me why the
changes don't appear in the PDF but only in the DVI output. All these
small bits should be explained somewhere.
------
These are my plans:
I started to work on the docs before I started the Win installer
project, the docs can be found here:
http://wiki.lyx.org/LyX/DocumentationDevelopment
We have lots and lots of questions in the lyx-users list that were
already answered some time ago, so I will describe the several features
with all its details in several documents. This will hopefully enable
the users to find a solution for their special problem without searching
in mailing lists.
These documents are a good starting point for
developers when they want to implement new functionality or support for
LaTeX-packages.
The basic things and informations of the special documents will be part
of the userguide.
To see what I mean have a look at the Floats/Figures/Tables manual I'm
currently working on (It is not yet ready!):
http://wiki.lyx.org/uploads/LyX/LyXDevelDocumentation/Tables.pdf
(http://wiki.lyx.org/uploads/LyX/LyXDevelDocumentation/Tables.rar)
It contains lots answers to special problems asked in the users-list but
also the basics.
The section about booktabs is for example a good test for the booktabs
implementation of LyX 1.5svn: Is the implementation feature complete?,
can the example tables be created easily enough?, etc..
The special docs as well as the basic userguide will have a detailed
description of every menu entry and toolbar button. The lack of this
information is currently the most annoying thing for new users.
The special docs can be used as testing documents before new versions
of LyX are released. This will hopefully avoid buggy releases like LyX
1.4.0. I noticed most of the bugs I reported for this release by
checking the math features using my math documentation:
http://wiki.lyx.org/LyX/LyXMathebefehle
This math manual will be the second specials documentation when it is
translated into English.
regards Uwe
