WARNING! WARNING! Danger, Will Robinson, Danger!
On Tue, Jan 04, 2005 at 02:31:06PM -0800, Jeremy C. Reed wrote:
> On Tue, 4 Jan 2005, [ISO-8859-1] Uwe Stïhr wrote:
> > In my opinion there should only be two books within the book: the
> > tutorial and the userguide.
> >
> > The tutorial can be called "LyX in three days", what would be an
> > appetizer for beginners. (As I once had to learn Delphi, I found a book
> > with the chapter "Delphi in 10 hours". Such a chapter eases to start
> > with a new program.)
> >
> > The userguide should contain the extended and customization doc.
>
> I am thinking of doing the extended and customization document in a second
> book.
Whatever you guys do, please don't expect it to end up back in the
official docs. We actually had that discussion before.
In fact, we had that discussion SEVERAL TIMES before. (About every 2
years or so.)
When i began the whole Documentation Project waaaaaaay back in 1995 or
1996, Matthias Ettrich's original manual was this huge, unnavigable
beast. It was so large, there was no way to maintain it effectively.
So, it was also hopelessly out of date.
You can see that the same has happened again, but this time, it's not
nearly as bad, due to the entire division into multiple docs as per my
original plan:
Introduction: The starting point and jumping-off pad.
Added after-the-fact because, what with everyone
speaking different mother-tongues, what *I* read when I
see "Advanced Features" and what someone else reads
when they see that same name for a doc end up being
worlds apart.
So, The Intro was a way to tell everyone where they
needed to go for what they wanted. It was also a place
for common introductory info that I found myself
copying verbatim into every single manual.
Tutorial: Summary of the User's Guide, with step-by-step instructions
for timid newbies.
User's Guide: Documents the basic, *stable* features.
At the time, I was focussed half-and-half on leery
LateXperts and resistant emigres from Winblows. Hence
the features chosen to grace the UG vs. those that went
in "Extended" (a.k.a. "Advanced Features"
a.k.a. "Additional Features" a.k.a. ...)
Extended: New features, moving-target features, layouts for LaTeX
classes favored in certain countries, advanced features
like the margin notes and parboxen, et cetera et cetera ad
nauseum.
Customization: As the name implies. Put in a separate manual because
this was, at the time, even MORE of a moving target
than the moving-target editing features of LyX.
Reference: It was SUPPOSED to be a developer-maintained doc
describing all of the more esoteric and arcane aspects of
LyX.
It ended up just describing the keybindings. And maybe
some of the menu bindings.
7 years after I ended my stint as head of the DocProject, the menu
layout & keybindings have drifted, and some more features have become
standard, but all in all, the docs aren't as out-of-date as they could
be, considering the complete lack of any work on them...
Oh... And I DEFINITELY suggest that you do "Extended" and
"Customization" in their own book. Or maybe books.
Put the keybindings in all of your books as Appendicies.
Those are my thoughts, and the train is arriving at my stop, so it's
approaching time for me to power down this laptop I'm typing on.
--
John Weiss
