On Mon, May 07, 2001 at 11:42:57AM -0700, [EMAIL PROTECTED] wrote:
>
> You've presented some good ideas. Anyone else care to weigh in? I suspect
> John W will have some strong thoughts on the matter - I'm not sure if he
> reads this list or not.
Oh, I listen. ;) Real life, however, intrudes from time to time, and
I can go for weeks without cleaning up my lyx-box. But when I have
something to say, I'm hard to shut up! :)
Anyway, both Mike and George should read this entire thing
thoroughly. My past experiences may save you future aggravation.
First, to the tone of the Intro. Yes, there are parts that are
strident, and yes, they are dated. Those parts were pretty much done
in the spirit of Matthias Ettrich's original "LyX Manifesto" at the
start of the realllly ooooolllllld docs that preceeded my efforts.
Second, I want to comment on Word's "ease" of using templates. I've
spent DAYS carefully massaging a Word template to get it to give me
even 50% of the consistency of LyX + LaTeX. Then, out of the blue,
one day, Word blithely redefines a bunch of my document styles. Never
mind what they were defined as in the template, Word decided that it
knew what I wanted better than me and went and trashed <name document
part here>. Worse: it does this regularly. I finally went and bought
the O'Reilly "Word Macros" reference and created an entire Macro
library to repair all of my custom styles whenever Word decided to
wreck one of my *.dot files.
In the end, I've spent almost as much time as I did writing the LaTeX2e
*.cls file --- from scratch --- for my grad-alma-mater's doctoral
thesis styles. Unlike writing "CU-thesis.cls", however, I *still*
have to keep reparing those @#$%^&(($% Word templates.
The only thing I'll concede to Word is its more immediate visual
feedback.
I think we can take the experience described above, iron out the tone
of frustration and aggravation, and present it in a
compare-and-contrast description of what LyX gives you over "document
templates".
Third:
Point Three:
> > For example, one of the things that I was thinking is that the
> > Extended Features documentation is rather linear, which can make
> > it difficult for new users to find things.
George, you've hit the nail on the head. Coming up with a good
organizational scheme was one of my original nightmares! Whole
chapters kept sloshing from the UG to Ref to Custom and back again (at
that time, there was no "Extended").
Here's the problem:
If the UG is too large, people don't read it at all: it takes too long
to find anything, not to mention to load and/or print.
IF you have the information spread over too many documents, again, it
takes too long to find anything.
If you don't put something in the UG, there's this silly political
implication that that feature is somehow "unimportant" or "too
esoteric".
Fourth:
> Might work. I've often wondered if we could recombine Extended,
> Customization, and (the almost thoroughly useless) Reference Guide into
> two, more compelling, documents.
RefG and Custom, yes. Extended, no. Here's why:
History:
Originally, the Reference Guide was going to be the "cutting edge"
document. I tried to design simple "entry-sections" that devvies
could fill in and stick somewhere in the RG. I (or a future Editor)
would then clean them up, move them to the proper RG chapter, and add
any cross-refs. The other documents could then be maintained and
updated by using the RefGuide as the information source.
Didn't work. No one even bothered to keep the keybindings up to
date. :P
So, Customization and the one or two useful chapters from the RG
should be merged into one doucment.
The "(Over)Extended LyX Manual" originally began life as "Advanced
Features". My idea was simple: "Info" told you which doc to start
with. "Tutorial" was where newbies went. UG was where the more
clueful user (or LaTeX die-hard) would start. It would document ---
with examples --- those features that everyone would be using 50-80%
of the time. Any neat-but-more-specialized features, like fax
support, would go in the "Advanced Features" doc. So, too, would the
documentation for user-defined *.layout files. For political reasons,
however, the name changed to "Extended" (some people got all in a huff
about the word "Advanced").
Maybe it and the UG should be renamed to "User's Guide, Volume 1" and
"User's Guide, Volume 2".
> > a similar manner. For example, the opening section of the User's
> > Guide has all the ear marks of being major propaganda, which I
> > have nothing against, but I wonder if it wouldn't be better to get
[snip]
> Yeah, most of the into in the UG could probably be moved to Intro.
Don't bother moving it. Let's drop the propaganda (a holdover from
the Matthias Ettrich days, anyhow ;) ) and just have a paragraph or
two "tooting our own horn", just to demonstrate to the M$ Word crowd
what they gain from LyX. And, we can be magnanamous and state what
you lose.
> > Also, maybe look at adding an FAQ or Q&A type document. There are lots of
> > similar questions asked on the LyX User's mailing list all the time. Herb
> > Voss has invested (I suspect) a great deal of time in developing his web
> > pages, but really, the user shouldn't have to go digging that far for many of
> > the answers he has up there...they should be in the documentation.
[snip!]
>
> Ahem, there is a much ignored FAQ in the documentation. It even points to
> Herb's site. Given that Herb's site is so good, but focussed a bit more on
> tips and tricks, I want the FAQ to cover the true FAQs,
[snip!}
I'm not on the lyx-users list anymore (too much traffic to keep up
with), so I can't be too sure of what I'm about to say. At the time I
was LyXDoc-Grand-Poobah, almost all of the FAQ that came through were
questions of the form "How Do I...?"
There *was*, indeed, once a document called "HowDoI.lyx". It was
supposed to be the de-facto FAQ, organized like an FAQ, with the title
"How Do I..." and chapters, sections, and subsections all having names
beginning with "..." and ending with "?". The "HowDoI.lyx" would give
a quick tip, if possible, and point the user to an appropriate
document and chapter/section/subsection/etc. that explained all in
greater detail. The rest of the documentation was *supposed* to
dovetail with this FAQ.
Didn't happen. No one bothered to fill in "HowDoI.lyx" beyond the 2
or 3 entries I put in there to start with. Alas, even if someone had,
I doubt anyone would have made sure it dovetailed with the other docs.
Last Topic: The "daunting" LyXDoc Style Sheet.
Sorry boys, but this one has to be strident ... or, better put, as
strict as a nun in a 50's era catholic school. There is no way around
this.
The Style Sheet grew out of my experiences as Editor. I'd have
volunteers. They would write their contributions in a vacuum,
ignoring the rest of the document. I would then spend enormous time
fixing what they sent me --- to the point where I could've written the
section myself from scratch with less effort. I would tell people
that we'd use Typewriter-style for codes and SansSerif for keybindings
and menus. Volunteers would come up with all sorts of weird
contortions of logic to explain away why they totally ignored this
standard. I'd find seven different forms of "remark-from-the-author"
... all seven in the same section from the same person. I'd find all
sorts of creative use of font, underlining, italicizing, and
boldfacing covering up totally uncreative content. I'd get
contributions that had barely any organization or structure. I'd
merge sections from different people together, and end up with a
chapter that switched from British English to American English to
formal speech to informal speech to obtuse speech willy-nilly!
Worst of all, I had to tell volunteers that the effort they made
needed fixing without invalidating their efforts, insulting them, and
generally sending them storming off in a huff. It was a major
tightrope act, and I fear that I wasn't too successful.
This, gentlemen, is why the Style Sheet is so strict and emphatic. If
you fail to specify *exactly* what the rules are, if you leave any
wiggle-room, your volunteers will send you whatever they feel like,
leaving you to either fix it or let the docs descend once more into
chaos. So, beware of wasted effort trodding the path that I already
walked.
--
John Weiss
"Not through coercion. Not by force. But by compassion. By
affection. And, a small fish." -His Holiness, the 14th Dalai Lama
